Коментарі у

Про концепцію Коментарі

Коментарі дають змогу залишати в коді нотатки, не впливаючи на те, як він виконується. Однорядковий коментар починається з // у будь-якому місці рядка. Компілятор ігнорує все від // до кінця цього рядка. Коли коментар стоїть після коду в тому самому рядку, його часто називають вбудованим коментарем. Багаторядковий коментар починається з /* і закінчується */ у будь-якому місці рядка. Компілятор ігнорує все, що між ними, охоплюючи один або кілька рядків.

// This is a single-line comment on its own line

x := 1 // This is an single-line comment inline with code
fmt.Println(x) // prints 1

/*
This is a valid
multiline comment.
*/

/* This is also a valid multi-line comment. */

Коментарі мають різне призначення залежно від того, де вони стоять.

Коментарі в коді

Коментарі в коді пояснюють, чому щось зроблено, а не що саме. Використовуймо їх, коли причина рішення не очевидна з коду:

results = results[1:] // skipping the header row

У більшості випадків чітко написаний код зрозумілий сам по собі, і коментарі не потрібні. Іноді коду потрібно робити щось складне або несподіване; такий код варто коментувати.

Документаційні коментарі

Документаційні коментарі використовують, щоб документувати пакет, змінну або функцію. Ця документація призначена для інших програмістів, які хочуть дізнатися, як використовувати код. Вона має на високому рівні пояснювати, що робить код і як його використовувати. Вона не повинна містити подробиць про те, як працює сам код. Документаційні коментарі стоять безпосередньо перед оголошенням, без порожнього рядка між коментарем і оголошенням. godoc розбирає їх, щоб згенерувати документацію пакета, як це видно на pkg.go.dev. Документаційний коментар має бути повним реченням, яке починається з назви ідентифікатора й закінчується крапкою.

Документаційні коментарі до експортованих ідентифікаторів (тих, що починаються з великої літери) потрапляють до згенерованої документації. Документаційні коментарі до неекспортованих ідентифікаторів (тих, що не починаються з великої літери) до неї не потрапляють, але все одно можуть давати корисний контекст у коді.

Коментарі, що документують пакети, починаються з назви пакета й описують, що робить пакет:

// Package kelvin provides tools to convert temperatures to and from Kelvin.
package kelvin

Коментарі, що документують функції, починаються з назви функції й описують, що робить функція, включно з її аргументами та поверненими значеннями:

// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
    return 0
}

Коментарі, що документують змінні, починаються з назви змінної й описують, що ця змінна представляє:

// TemperatureFahrenheit represents a certain temperature in degrees Fahrenheit.
var TemperatureFahrenheit float64

Повну специфікацію документаційних коментарів дивіться в посібнику з документування Go.