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

Комментарии – это строки в коде компьютерных программ, которые игнорируются компиляторами и интерпретаторами. Включение комментариев в программы делает код более читабельным и понятным для людей, поскольку они предоставляют дополнительную информацию или объясняют, что делает тот или иной блок кода.

В зависимости от цели программы, комментарии могут также служить примечаниями или напоминаниями. А еще с их помощью вы можете помочь другим программистам понять, что делает ваш код.

В целом писать комментарии хорошо и полезно, особенно если делать это прямо во время создания и обновления программы – ведь позже вы можете забыть, что именно вы имели в виду, а написанные позже комментарии могут оказаться не такими точными.

Синтаксис комментариев

В Go комментарии начинаются с двух слешей (//) и продолжаются до конца строки. Между слешами и текстом комментария принято ставить пробел.

Общий вид комментариев таков:

// This is a comment

Комментарии не выполняются интерпретатором, поэтому при запуске программа не выводит их. Комментарии содержатся в исходном коде для чтения людьми, а не для выполнения компьютерами.

В базовой программе «Hello, World!» Комментарий может выглядеть так:

package main

import (

"fmt"

)

func main() {

// Print “Hello, World!” to console
fmt.Println("Hello, World!")

}

В цикле for, который выполняет итерации по фрагменту, комментарии могут выглядеть следующим образом:

package main

import (

"fmt"

)

main() {

// Define sharks variable as a slice of strings
sharks := []string{"hammerhead", "great white", "dogfish", "frilled", "bullhead", "requiem"}

// For loop that iterates over sharks list and prints each string item
for _, shark := range sharks {

fmt.Println(shark)

}

}

Комментарии должны иметь те же отступы, что и код, который они объясняют. То есть если функция определена без отступа, то и комментарий для нее тоже должен быть отступа

Например, в этом фрагменте комментарии следуют за каждым уровнями кода:

package main

import "fmt"

const favColor string = "blue"

func main() {

var guess string

// Create an input loop
for {

// Ask the user to guess my favorite color
fmt.Println("Guess my favorite color:")

// Try to read a line of input from the user. Print out the error 0
if _, err := fmt.Scanln(&guess); err != nil {

fmt.Printf("%s\n", err)

return

}

// Did they guess the correct color?
if favColor == guess {

// They guessed it!
fmt.Printf("%q is my favorite color!\n", favColor)

return

}

// Wrong! Have them guess again.
fmt.Printf("Sorry, %q is not my favorite color. Guess again.\n", guess)

}

}

Комментарии должны помогать программистам, которые совместно работают над проектом (в том числе и самому автору проекта). Если вы не можете должным образом поддерживать комментарии и обновлять их вместе с базой кода, лучше вообще не включать комментарии. Код без комментариев лучше, чем код с неправильными комментариями, которые противоречат коду.

Комментируя код, вы должны искать ответ на вопрос «почему?», а не «что?» или «как?». Если код не очень сложный или запутанный, программисту, как правило, достаточно просмотреть его, чтобы понять, что и как он делает. Поэтому комментарии обычно сосредоточены на том, почему нужен тот или иной блок кода.

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

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

Блочные комментарии можно использовать для объяснения более сложного или потенциально незнакомого кода.

Создать блочные комментарии в Go можно двумя способами. Первый – использовать два слеша в начале каждой строки комментария.

// First line of a block comment
// Second line of a block comment

Второй вариант – это открывающие (/*) и закрывающие теги (*/). Для документирования кода принято использовать первый вариант (//). Синтаксис / * … * / обычно используется для отладки (об этом немного позже).

/*
Everything here
will be considered
a block comment
*/

В этом примере блочный комментарий определяет, что происходит в функции MustGet():

// MustGet will retrieve a url and return the body of the page.
// If Get encounters any errors, it will panic.
func MustGet(url string) string {

resp, err := http.Get(url)

if err != nil {

panic(err)

}

// don't forget to close the body
defer resp.Body.Close()

var body []byte

if body, err = ioutil.ReadAll(resp.Body); err != nil {

panic(err)

}

return string(body)

}

Обычно комментарии Go отображаются в начале экспортированных функций; эти комментарии документируют код. Также блочные комментарии используются, когда операции сложные и поэтому требуют подробного объяснения. Однако следует избегать чрезмерного количества комментариев в коде: доверяйте другим программистам Go (если только вы не пишете для определенной аудитории).

Встроенные комментарии

Встроенные (или строчные) комментарии находятся в одной строке с операторами, следуют за кодом. Как и другие комментарии, они начинаются с двух слешей. Ставить пробел после слеша не обязательно, но так принято делать.

Как правило, встроенные комментарии выглядят так:

[code]  // Inline comment about the code

Встроенные комментарии следует использовать с осторожностью, но они могут помочь вам объяснить запутанные или неочевидные строки в коде. Они также позволяют вам сделать для себя примечания на будущее или помочь разобраться тем разработчикам, которые не знакомы со всеми аспектами кода.

Например, если в программах Go вы не используете много вычислений, ваши соавторы могут не знать, что следующая строка создает сложное число, поэтому вы можете включить встроенный комментарий об этом:

z := x % 2  // Get the modulus of x

Вы также можете использовать встроенные комментарии, чтобы объяснить причину того или иного действия или предоставить дополнительную информацию:

x := 8  // Initialize x with an arbitrary number

Использовать встроенные комментарии стоит только тогда, когда это необходимо и полезно для человека, читающего программу.

Комментарии в тестировании программ

Помимо документирования кода комментарии также применяются в тестировании. Вы можете использовать открывающие (/ *) и закрывающие теги (* /) для создания блочного комментария. Это закомментирует код, который не нужно выполнять во время тестирования или отладки программы. Столкнувшись с ошибками после внедрения нового кода, вы можете закомментировать некоторые из них, чтобы выяснить источник неполадки.

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

// Function to add two numbers
func addTwoNumbers(x, y int) int {

sum := x + y

return sum

}

// Function to multiply two numbers
func multiplyTwoNumbers(x, y int) int {

product := x * y

return product

}

func main() {

/*

In this example, we're commenting out the addTwoNumbers
function because it is failing, therefore preventing it from executing.
Only the multiplyTwoNumbers function will run
a := addTwoNumbers(3, 5)
fmt.Println(a)

*/

m := multiplyTwoNumbers(5, 9)

fmt.Println(m)

}

Примечание: Такое комментирование кода должно выполняться только в целях тестирования. Не оставляйте фрагменты закомментированного кода в вашей окончательной версии программы.

Закомментированный с помощью тегов / * и * / код позволяет испытать различные подходы программирования, а также поможет найти источник ошибки.

Заключение

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

Разумное комментирование кода в Go также позволит вам использовать инструмент Godoc. Godoc – это инструмент, который извлекает комментарии из кода и на их основе генерирует документацию для программы Go.

Tags: