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

Вступление

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

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

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

Комментарии в Go начинаются с набора косых черт (//) и продолжаются до конца строки. Идиоматично иметь пробел после набора косых черт.

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

// This is a comment

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

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

hello.go

package main

import (
    "fmt"
)

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

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

sharks.go

package main

import (
    "fmt"
)

func 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)
    }
}

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

Например, вот как комментируется функцияmain, с комментариями после каждого уровня отступа кода:

color.go

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)
    }
}

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

Комментируя код, вы должны стремиться ответить наwhy за кодом, а не наwhat илиhow. Если код не является особенно сложным, просмотр кода обычно может дать ответ наwhat илиhow, поэтому комментарии обычно сосредоточены вокругwhy.

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

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

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

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

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

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

function.go

// 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; эти комментарии также создают документацию вашего кода. Блочные комментарии также используются, когда операции менее просты и поэтому требуют подробного объяснения. За исключением функций документирования, вы должны избегать чрезмерного комментирования кода и доверять другим программистам понимание Go, если вы не пишете для определенной аудитории.

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

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

[code]  // Inline comment about the code

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

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

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

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

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

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

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

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

multiply.go

// 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)
}

[.note] #Note: Комментировать код следует только в целях тестирования. Не оставляйте фрагменты закомментированного кода в окончательной программе.
#

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

Заключение

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

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

TOC

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

Вступление

Заключение

Related