Effective Go: 注释

·  阅读 49

这是我参与11月更文挑战的第14天,活动详情查看:2021最后一次更文挑战

Go 提供 C 风格的 /* */ 块注释和 C++ 风格的 // 行注释。行注释是规范使用;块注释主要作为包注释出现,但在表达式中或禁用大量代码时很有用。

godoc 处理 Go 源文件可以提取有关包内容的文档。在最上层声明的注释,没有换行符,与声明一起被提取出来作为项目的解释性文本。这些评论的性质和风格决定了 godoc 生成的文档的质量。

每个包都应该有一个包注释,在包之前写上块注释。对于多文件包,包注释只需要出现在一个文件中,任何一个都可以。包注释应介绍包并提供与整个包相关的信息。它将首先出现在 godoc 页面上,并应设置后面的详细文档。下面是个案例:

/*
Package regexp implements a simple library for regular expressions.

The syntax of the regular expressions accepted is:

    regexp:
        concatenation { '|' concatenation }
    concatenation:
        { closure }
    closure:
        term [ '*' | '+' | '?' ]
    term:
        '^'
        '$'
        '.'
        character
        '[' [ '^' ] character-ranges ']'
        '(' regexp ')'
*/
package regexp
复制代码

如果包功能很简单,那么包的注释可以很简洁

// Package path implements utility routines for
// manipulating slash-separated filename paths.
复制代码

注释不需要额外的格式,例如各种星星横幅。生成的输出甚至可能不会以固定宽度的字体呈现,因此不要依赖间距进行对齐,gofmt会帮我们处理这个问题。注释是未解释的纯文本,因此 HTML 格式的注释和其他注释(例如 *this* )将逐字复制,不应使用。 godoc 所做的一项调整是以固定宽度的字体显示缩进文本,适用于程序片段。 fmt 包的包注释遵循了已上原则是个很好的例子。

根据上下文,godoc 甚至可能不会重新格式化注释,因此请确保它们直接看起来不错:使用正确的拼写、标点符号和句子结构,折叠长行等。

在包内,紧接在顶级声明之前的任何注释都用作该声明的文档注释。程序中的每个导出(大写)名称都应该有一个文档注释

文档注释作为完整的句子效果最好,它允许各种自动演示。第一句话应该是一个句子摘要,以被声明的名字开头,如下:

// Compile parses a regular expression and returns, if successful,
// a Regexp that can be used to match against text.
func Compile(str string) (*Regexp, error) {
复制代码

如果每个 doc 注释都以其描述的项目名称开头,则可以使用 go 工具的 doc 子命令并通过 grep 运行输出。 想象一下,你如果不记得上述那个方法名字“Compile”,但正在寻找这个正则表达式的解析函数,那你可以运行下面这个命令来找到它

$ go doc -all regexp | grep -i parse
复制代码

如果包中的所有文档注释都以“This function...”开头,grep 将无法帮助您记住名称。 但是因为包以名称开始每个文档注释,所以您会看到类似这样的内容,它会回忆起您正在寻找的单词。

$ go doc -all regexp | grep -i parse
    Compile parses a regular expression and returns, if successful, a Regexp
    MustCompile is like Compile but panics if the expression cannot be parsed.
    parsed. It simplifies safe initialization of global variables holding
$
复制代码

Go 的声明语法允许对声明进行分组。 单个文档注释可以引入一组相关的常量或变量。 由于提供了整个声明,这样的评论通常比较敷衍的。

// Error codes returned by failures to parse an expression.
var (
    ErrInternal      = errors.New("regexp: internal error")
    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
    ...
)
复制代码

分组同样可以体现项目之间存在某种关系,例如下面这个例子

var (
    countLock   sync.Mutex
    inputCount  uint32
    outputCount uint32
    errorCount  uint32
)
复制代码
分类:
后端
标签: