Написание комментариев в Go
General | Комментировать запись
Комментарии – это строки в коде компьютерных программ, которые игнорируются компиляторами и интерпретаторами. Включение комментариев в программы делает код более читабельным и понятным для людей, поскольку они предоставляют дополнительную информацию или объясняют, что делает тот или иной блок кода.
В зависимости от цели программы, комментарии могут также служить примечаниями или напоминаниями. А еще с их помощью вы можете помочь другим программистам понять, что делает ваш код.
В целом писать комментарии хорошо и полезно, особенно если делать это прямо во время создания и обновления программы – ведь позже вы можете забыть, что именно вы имели в виду, а написанные позже комментарии могут оказаться не такими точными.
Синтаксис комментариев
В 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 (если только вы не пишете для определенной аудитории).
Встроенные комментарии
Встроенные (или строчные) комментарии находятся в одной строке с операторами, следуют за кодом. Как и другие комментарии, они начинаются с двух слешей. Ставить пробел после слеша не обязательно, но так принято делать.
Как правило, встроенные комментарии выглядят так:
// 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: Go