如何在Go中写评论

介绍

注释是存在于计算机程序中被编译器和解释器忽略的行。在程序中包含注释使代码对人类来说更具可读性，因为它提供了一些关于程序每个部分正在做什么的信息或解释。

根据您的程序的目的，注释可以作为您自己的注释或提醒，或者可以编写它们以使其他程序员能够理解您的代码在做什么。

一般来说，在编写或更新程序时写注释是个好主意，因为以后很容易忘记你的思考过程，而且从长远来看，以后写的注释可能不太有用。

注释语法

Go 中的注释以一组正斜杠 (//) 开始，一直持续到行尾。在一组正斜杠之后有一个空格是惯用的。

通常，注释看起来像这样：

// This is a comment

注释不执行，因此在运行程序时不会显示注释。注释在源代码中供人类阅读，而不是供计算机执行。

在“你好，世界！” 程序，注释可能如下所示：

你好.go

package main

import (
    "fmt"
)

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

在遍历切片的 for 循环中，注释可能如下所示：

鲨鱼.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 函数的注释方式，代码的每个缩进级别后面都有注释：

颜色.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() 函数中发生的情况：

函数.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，除非你是为特定的受众编写的。

内联评论

内联注释出现在语句的同一行，跟在代码本身之后。像其他评论一样，它们以一组正斜杠开头。同样，正斜杠后不需要有空格，但这样做被认为是惯用的。

通常，内联注释看起来像这样：

[code]  // Inline comment about the code

内联注释应该谨慎使用，但可以有效地解释代码中棘手或不明显的部分。如果您认为您将来可能不记得您正在编写的代码行，或者您正在与您认识的可能不熟悉代码的所有方面的人合作，它们也很有用。

例如，如果您在 Go 程序中不使用大量数学，您或您的合作者可能不知道以下内容创建了一个复数，因此您可能希望包含一个内联注释：

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

您还可以使用内联注释来解释做某事的原因，或者提供一些额外的信息，例如：

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

您应该只在必要时使用内嵌注释，并且它们可以为阅读程序的人提供有用的指导。

注释掉测试代码

除了使用注释来记录代码之外，您还可以使用开始标记 (/*) 和结束标记 (*/) 创建块注释。这允许您在测试或调试当前正在创建的程序时注释掉不想执行的代码。也就是说，当您在实现新的代码行后遇到错误时，您可能希望将其中的一些注释掉，看看您是否可以解决确切的问题。

使用 /* 和 */ 标签还可以让您在确定如何设置代码时尝试替代方案。您还可以在继续处理代码的其他部分时使用块注释来注释失败的代码。

乘法.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)
}

注意：注释掉代码只能用于测试目的。不要在最终程序中留下注释掉的代码片段。

使用 /* 和 */ 标签注释掉代码可以让您尝试不同的编程方法，并通过系统地注释和运行程序的一部分来帮助您找到错误的根源。

结论

在您的 Go 程序中使用注释有助于使您的程序对人类（包括您未来的自己）更具可读性。添加相关且有用的适当注释可以使其他人更轻松地与您在编程项目上进行协作，并使您的代码的价值更加明显。

在 Go 中正确注释您的代码也将允许您使用 Godoc 工具。 Godoc 是一个工具，可以从你的代码中提取注释并为你的 Go 程序生成文档。