3. 注释

注释对 Go 语言程序的可读性非常重要。注释应该做的三件事中的一件：

注释应该解释其作用。
注释应该解释其如何做的。
注释应该解释其原因。

第一种形式是公共符号注释的理想选择：

第二种形式非常适合在方法中注释：


var results []chan error
for _, dep := range a.Deps {
        results = append(results, execute(seen, dep))

第三种形式是独一无二的，因为它不会取代前两种形式，但与此同时它并不能代替前两种形式。此形式的注解用以解释代码的外部因素。这些因素脱离上下文后通常很难理解，此注释的为了提供这种上下文。

return &v2.Cluster_CommonLbConfig{
    // Disable HealthyPanicThreshold
        HealthyPanicThreshold: &envoy_type.Percent{
            Value: 0,
        },
}

在此示例中，无法清楚地明白 HealthyPanicThreshold 设置为零百分比的效果。需要注释 0 值将禁用 panic 阀值。

我之前谈过，变量或常量的名称应描述其目的。向变量或常量添加注释时，该注释应描述变量内容，而不是变量目的。

在此示例中，注释描述了为什么 randomNumber 被赋值为6，以及6来自哪里。注释没有描述 randomNumber 的使用位置。还有更多的栗子：


    StatusContinue           = 100 // RFC 7231, 6.2.1
    StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2
    StatusProcessing         = 102 // RFC 2518, 10.1

在HTTP的上下文中，数字 100 被称为 StatusContinue，如 RFC 7231 第 6.2.1 节中所定义。

是包的文档，所以应该始终为包中声明的每个公共符号 — 变量、常量、函数以及方法添加注释。

以下是 Google Style 指南中的两条规则:

任何既不明显也不简短的公共功能必须予以注释。
无论长度或复杂程度如何，对库中的任何函数都必须进行注释 ```golang package ioutil

// ReadAll reads from r until an error or EOF and returns the data it read. // A successful call returns err == nil, not err == EOF. Because ReadAll is // defined to read from src until EOF, it does not treat an EOF from Read // as an error to be reported. func ReadAll(r io.Reader) ([]byte, error)

这条规则有一个例外; 您不需要注释实现接口的方法。 具体不要像下面这样做：
```golang
// Read implements the io.Reader interface
func (r *FileReader) Read(buf []byte) (int, error)

这个注释什么也没说。它没有告诉你这个方法做了什么，更糟糕是它告诉你去看其他地方的文档。在这种情况下，我建议完全删除该注释。

请注意，LimitedReader 的声明就在使用它的函数之前，而 LimitedReader.Read 的声明遵循 LimitedReader 本身的声明。尽管 LimitedReader.Read 本身没有文档，但它清楚地表明它是 io.Reader 的一个实现。

粗劣的代码的注释高亮显示是不够的。如果你遇到其中一条注释，则应提出问题，以提醒您稍后重构。只要技术债务数额已知，它是可以忍受的。

标准库中的惯例是注意到它的人用 TODO(username) 的样式来注释。

// TODO(dfc) this is O(N^2), find a faster way to do this.

注释 username 不是该人承诺要解决该问题，但在解决问题时他们可能是最好的人选。其他项目使用 TODO 与日期或问题编号来注释。

函数应该只做一件事。如果你发现自己在注释一段与函数的其余部分无关的代码，请考虑将其提取到它自己的函数中。

除了更容易理解之外，较小的函数更易于隔离测试，将代码隔离到函数中，其名称可能是所需的所有文档。