МиниГо #4: Комментарии

Это четвертый урок нашего путешествия по изучению языка программирования Go (Golang) в котором мы поговорим про комментарии, зачем они нужны и как применять.

Строчные комментарии

Go игнорирует текст справа от //:

// This entire line is ignored by the compiler.
// fmt.Println("Does NOT print")
fmt.Println("This gets printed!") // This part gets ignored

Блочные комментарии

Все строки между /* и */ будут проигнорированы:

/*
This is ignored.
This is also ignored.
fmt.Println("This WON'T print!")
*/

Godoc

В Go есть инструмент для автоматической генерации документации из исходного кода Go: Godoc.

Из сообщения в блоге, анонсировавшего его в 2011 году:

Godoc парсит исходный код Go, включая комментарии, и создает документацию в виде HTML или обычного текста.

Посмотрите пример в формате HTML: zip — GoDoc.

Godoc следует некоторым простым соглашениям.

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

Этот тип комментария должен присутствовать в одном из исходных файлов пакета:

// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort

Комментарии к идентификаторам верхнего уровня

Это формат для описания функции верхнего уровня, const, var и т.д.:

// enterOrbit causes Superman to fly into low Earth orbit, a position
// that presents several possibilities for planet salvation.
func enterOrbit() os.Error {
  ...
}

Примеры кода в комментариях

Текст с отступами внутри комментария будет отображаться Godoc как предварительно отформатированный блок:

// fight can be used on any enemy and returns whether Superman won.
//
// Examples:
//
//  fight("a random potato")
//  fight(LexLuthor{})
//
func fight(enemy interface{}) bool {
  ...
}

Комментарии к ошибкам (багам)

Godoc игнорирует большинство комментариев, которые не находятся прямо над элементом верхнего уровня. Исключение составляют комментарии к ошибкам (багам): они будут включены в документацию пакета в раздел «Ошибки» (англ. — Bugs):

// BUG(name): The rule Title uses for word boundaries does not handle Unicode punctuation properly.

Текст в блоке со скобками — это имя пользователя, который может предоставить дополнительную информацию об ошибке.

Примечания об устаревании

Элементы, которые стали излишними или устаревшими, могут быть помечены в комментариях к документу параграфом, начинающимся с «Deprecated:», за которым следует информация об устаревании:

// ModTime returns the modification time in UTC using the legacy
// ModifiedDate and ModifiedTime fields.
//
// Deprecated: Use Modified instead.
func (h *FileHeader) ModTime() time.Time {
  return msDosTimeToTime(h.ModifiedDate, h.ModifiedTime)
}

Мы изучили общую тему про комментарии, советую изучить документацию по ссылке выше, чтобы больше понимать про Godoc.