3.6 💬 Комментарии и документация

Код без комментариев — как инструмент без инструкции. Комментарии в Go важны не только для чтения кода, но и для автоматической генерации документации с помощью встроенного инструмента godoc.

✍️ Виды комментариев

Go поддерживает два типа комментариев:

• Однострочные — начинаются с // и продолжаются до конца строки:

  // Это однострочный комментарий
  fmt.Println("Hello")
  

• Многострочные — заключаются между /* и */, могут занимать несколько строк:

  /*
     Это многострочный
     комментарий
  */
  

Однако в Go принято использовать однострочные комментарии почти всегда.

📄 Документационные комментарии

Go использует простую, но мощную систему документации. Достаточно прокомментировать функции, пакеты или структуры — и godoc на основе этих комментариев создаст читаемую справку.

📌 Главное правило: комментарий должен начинаться с имени объекта, который он описывает.

Пример:

// Add складывает два целых числа и возвращает результат.
func Add(a int, b int) int {
    return a + b
}

Такой комментарий будет автоматически отображён в godoc или в IDE при наведении курсора.

🧰 Как посмотреть документацию

• В терминале:

  go doc fmt.Println
  

  или

  go doc ./...
  

• В браузере: https://pkg.go.dev — официальный каталог пакетов с документацией.

✅ Хорошая документация — это:

• Простые и понятные фразы.
• Примеры использования.
• Начало комментария с имени функции или типа.
• Комментарии ко всем экспортируемым объектам (с заглавной буквы).

📌 Главное из главы

• Используй // для комментариев, избегай /* */.
• Начинай документационные комментарии с имени функции, переменной или типа.
• Генерация документации происходит автоматически с помощью godoc.
• Документация важна не только для других, но и для тебя самого в будущем.

В следующей главе ты узнаешь, как проводить тестирование кода на Go.