Комментарии: однострочные, многострочные и документирование

Комментарии и документирование кода

Краткое описание

В этом уроке изучаем все способы комментирования кода в Go: однострочные комментарии для пояснений, многострочные для больших блоков текста и специальные документирующие комментарии для автоматической генерации документации. Разбираем best practices, метки TODO/FIXME и учимся писать полезные комментарии, которые отвечают на вопрос “зачем?”, а не “что?”.

Ключевые концепции

Зачем нужны комментарии

Комментарии — это текст в коде, который игнорируется компилятором и предназначен для людей. Они помогают:

  • Объяснить сложную логику
  • Отметить места для доработки (TODO)
  • Временно отключить код
  • Создать документацию для функций и типов
  • Оставить заметки для других разработчиков

Важно: комментарии не влияют на работу программы — компилятор их полностью игнорирует.

Три типа комментариев в Go

  1. Однострочные — // (основной способ)
  2. Многострочные (блочные) — /* ... */
  3. Документирующие — специальный формат для GoDoc

Однострочные комментарии

Синтаксис

Две косые черты // — всё после них до конца строки игнорируется:

// Это комментарий
var age int = 25  // Комментарий в конце строки

Способы использования

1. Комментарий над кодом (рекомендуется):

// Комментарий перед объявлением переменной
var name string = "Сергей"

2. Комментарий в конце строки:

var age int = 25  // Возраст пользователя

3. Несколько строк подряд:

// Комментарии могут идти подряд
// чтобы создать эффект многострочного текста
// каждая строка начинается с //

4. Временное отключение кода:

// fmt.Println("Эта строка не выполнится")
// var unused int = 100

Горячие клавиши

Для быстрого комментирования/раскомментирования используйте:

  • macOS: Cmd + /
  • Windows/Linux: Ctrl + /

Выделите несколько строк и нажмите комбинацию — все строки закомментируются.

Метки TODO, FIXME, NOTE

Специальные метки помогают отметить важные места в коде:

// TODO: Добавить валидацию возраста
// FIXME: Исправить обработку пустых строк
// NOTE: Максимальный возраст — 120 лет
// HACK: Временное решение, переделать позже
// BUG: Известная проблема с UTF-8

Расширения IDE: многие редакторы (VS Code, GoLand) имеют расширения для подсветки таких меток. Например, в VS Code можно установить “TODO Highlight”.

Где размещать комментарии

Правильно:

// Комментарий над переменной
var temperature int = 20

var result int = age * 12  // Комментарий справа

Неправильно:

                          // Комментарий НЕ над переменной
var temperature int = 20

Комментарий должен быть либо над кодом, либо справа на той же строке.

Многострочные (блочные) комментарии

Синтаксис

Начинаются с /* и заканчиваются */:

/*
   Это многострочный комментарий.
   Он может занимать несколько строк
   и удобен для длинных пояснений.
*/

Варианты использования

1. Однострочный блочный комментарий:

/* Простой блочный комментарий */
fmt.Println("Программа запущена")

2. Многострочный:

/*
   Многострочный комментарий для описания алгоритма:
   1. Инициализируем переменные
   2. Выполняем вычисления
   3. Выводим результат
*/
var x int = 10

3. Внутри строки кода:

var result int = 42 /* временное значение */

4. Стиль со звёздочками:

/*
 * Стиль с звездочками для визуального выделения
 * (распространен в других языках, но не идиоматичен для Go)
 * Каждая строка начинается со звездочки
 */

Вложенные комментарии НЕ поддерживаются

Ошибка:

/* Внешний комментарий
   /* Попытка вложенного комментария */
   Это вызовет ошибку!
*/

Компилятор закроет комментарий на первом */, остальной текст вызовет синтаксическую ошибку.

Правильно (если нужно закомментировать блочный комментарий):

// /* Закомментированный блочный комментарий
// Текст
// */

ASCII-арт в комментариях

Технически возможен, но не рекомендуется:

/*
   ╔══════════════════════════════════════╗
   ║  ASCII-арт в комментариях            ║
   ║  Можно использовать для заголовков   ║
   ╚══════════════════════════════════════╝
*/

Почему не стоит: трата времени, усложняет код, выглядит непрофессионально в современных проектах.

Когда использовать блочные комментарии

Подходят для:

  • Лицензионных заголовков файлов
  • Больших блоков текста (описания алгоритмов)
  • Временного отключения больших кусков кода

Не рекомендуется для:

  • Обычных пояснений (используйте //)
  • Коротких комментариев

Документирующие комментарии (GoDoc)

Что такое GoDoc

Go имеет встроенный инструмент go doc для автоматической генерации документации из специально оформленных комментариев.

Правила оформления

1. Комментарий непосредственно перед объявлением:

// Greet приветствует пользователя по имени.
func Greet(name string) string {
    return fmt.Sprintf("Привет, %s!", name)
}

2. Первое предложение — краткое описание:

Должно начинаться с имени объявляемой сущности:

// MaxAttempts определяет максимальное количество попыток подключения.
const MaxAttempts = 3

3. Полная документация с примерами:

// Greet приветствует пользователя по имени.
// Функция принимает имя пользователя и возвращает строку приветствия.
//
// Параметры:
//   - name: имя пользователя для приветствия
//
// Возвращает строку с персональным приветствием.
//
// Пример использования:
//
//  var message string = Greet("Сергей")
//  fmt.Println(message) // Выведет: Привет, Сергей!
func Greet(name string) string {
    return fmt.Sprintf("Привет, %s!", name)
}

Важно: пример кода отделяется пустой строкой и отступается табуляцией.

Документирование пакета

В начале файла (обычно в doc.go или в главном файле пакета):

// Package main демонстрирует использование документирующих комментариев в Go.
// Комментарии автоматически извлекаются инструментом go doc.
package main

Просмотр документации

Команды:

go doc Greet           # документация функции Greet
go doc MaxAttempts     # документация константы
go doc -all            # вся документация пакета
godoc -http=:6060      # локальный веб-сервер с документацией

Эффект в IDE

При наведении курсора на функцию/переменную IDE показывает документирующий комментарий:

Без комментария:

func Greet(name string) string

С комментарием:

func Greet(name string) string

Greet приветствует пользователя по имени.
Функция принимает имя пользователя и возвращает строку приветствия.

Пример использования:
    var message string = Greet("Сергей")

Best Practices

1. Комментарии должны отвечать на “ЗАЧЕМ?”, а не “ЧТО?”

Плохо (объясняет очевидное):

// Это переменная age
var age int = 25

// Выводим возраст на экран
fmt.Println(age)

Хорошо (объясняет причину):

// Используем фиксированный возраст для демонстрации
// В production значение будет браться из базы данных
var age int = 25

// Временный вывод для отладки; удалить перед релизом
fmt.Println(age)

2. Осмысленные имена лучше комментариев

Плохо:

var a int = 25  // Возраст пользователя

Хорошо:

var userAge int = 25  // Комментарий не нужен!

Если из имени переменной понятно её назначение, комментарий избыточен.

3. Используйте однострочные комментарии

Рекомендуется:

// Первая строка
// Вторая строка
// Третья строка

Не рекомендуется:

/*
   Первая строка
   Вторая строка
   Третья строка
*/

Однострочные комментарии легче добавлять/удалять горячими клавиши.

4. Не увлекайтесь комментированием

Избыточно:

// Объявляем переменную userName типа string
var userName string = "Иван"

// Объявляем переменную userAge типа int
var userAge int = 25

// Складываем числа
var sum int = 10 + 20

Такие комментарии создают шум и бесполезны.

5. Удаляйте мёртвый код

Плохо:

// var oldVersion int = 1
// func oldFunction() { }
// type OldStruct struct { }

Не храните закомментированный код месяцами. Используйте систему контроля версий (Git) — старый код всегда можно восстановить из истории.

6. Объясняйте нетривиальную логику

Хорошо:

// Игнорируем ошибку для обратной совместимости с версией 1.0
// TODO: удалить после миграции всех клиентов на 2.0
_ = processData()

// Умножаем на 1.15 для учёта НДС 15%
var totalPrice = basePrice * 1.15

7. Документируйте публичные API

Если вы пишете библиотеку или пакет, который будут использовать другие:

// NewClient создаёт новый HTTP клиент с таймаутом.
// Возвращает ошибку, если timeout меньше 1 секунды.
func NewClient(timeout time.Duration) (*Client, error) {
    // ...
}

8. Не используйте комментарии для версионирования

Плохо:

// v1.0 - Иван - 01.01.2024 - Создал функцию
// v1.1 - Мария - 15.01.2024 - Добавила проверку
// v1.2 - Пётр - 20.01.2024 - Исправил баг
func Calculate() {
    // ...
}

Для этого существует Git и его история коммитов.

Практические примеры

Полный пример с разными типами комментариев 

// Package main демонстрирует использование комментариев в Go.
package main

import "fmt"

// MaxAttempts определяет максимальное количество попыток подключения.
// Значение по умолчанию установлено в 3 для баланса между
// надежностью и производительностью.
const MaxAttempts = 3

// Greet приветствует пользователя по имени.
// Функция принимает имя пользователя и возвращает строку приветствия.
//
// Параметры:
//   - name: имя пользователя для приветствия
//
// Возвращает строку с персональным приветствием.
//
// Пример использования:
//
//  var message string = Greet("Сергей")
//  fmt.Println(message) // Выведет: Привет, Сергей!
func Greet(name string) string {
    return fmt.Sprintf("Привет, %s!", name)
}

func main() {
    // TODO: Добавить валидацию имени
    var message string = Greet("Сергей")
    fmt.Println(message)

    // Используем константу для ограничения попыток
    fmt.Printf("Максимум попыток: %d\n", MaxAttempts)

    /*
       Временно отключенный код для тестирования
       for i := 0; i < 10; i++ {
           fmt.Println(i)
       }
    */

    // FIXME: Оптимизировать этот участок кода
    var result int = heavyCalculation()
    fmt.Println(result)
}

// Временная заглушка для демонстрации
func heavyCalculation() int {
    return 42
}

Важные моменты

1. Go поддерживает UTF-8 Комментарии на русском языке полностью поддерживаются:

// Комментарий на русском
var температура int = 20  // Тоже работает

2. Комментарии не замедляют программу Компилятор полностью удаляет комментарии — они не влияют на производительность.

3. IDE помогает с комментариями

  • Автоматическая подсветка TODO/FIXME
  • Превью GoDoc при наведении
  • Горячие клавиши для комментирования

4. GoDoc — мощный инструмент Документирующие комментарии автоматически становятся документацией на pkg.go.dev для публичных пакетов.

5. Не все комментарии полезны Лучше никакого комментария, чем плохой комментарий, который объясняет очевидное.

6. Комментарии устаревают При изменении кода не забывайте обновлять комментарии. Устаревший комментарий хуже отсутствия комментария.

7. Блочные комментарии неудобны Их нельзя быстро закомментировать/раскомментировать горячими клавишами. Предпочитайте //.

Что запомнить

  • Комментарии игнорируются компилятором
  • // — однострочные (основной способ)
  • /* */ — многострочные (используются редко)
  • Вложенные /* */ не поддерживаются
  • Горячие клавиши: Cmd+/ (macOS), Ctrl+/ (Windows)
  • TODO, FIXME, NOTE — стандартные метки
  • Документирующие комментарии начинаются с имени сущности
  • GoDoc автоматически генерирует документацию
  • Команды: go doc, go doc -all, godoc -http=:6060
  • Комментарий отвечает на “ЗАЧЕМ?”, а не “ЧТО?”
  • Осмысленные имена лучше комментариев
  • Не комментируйте очевидное
  • Удаляйте закомментированный код (используйте Git)
  • Документируйте публичные API
  • ASCII-арт не рекомендуется
  • Обновляйте комментарии при изменении кода

Полезные ссылки