3. 注释

在我们继续讨论更大的项目之前，我想花几分钟时间谈论一下注释。

Good code has lots of comments, bad code requires lots of comments. (好的代码有很多注释，坏代码需要很多注释。) — Dave Thomas and Andrew Hunt (The Pragmatic Programmer)

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

  1. 注释应该解释其作用。
  2. 注释应该解释其如何做的。
  3. 注释应该解释其原因。

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

  1. // Open opens the named file for reading.
  2. // If successful, methods on the returned file can be used for reading.

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

  1. // queue all dependant actions
  2. var results []chan error
  3. for _, dep := range a.Deps {
  4.         results = append(results, execute(seen, dep))
  5. }

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

  1. return &v2.Cluster_CommonLbConfig{
  2.     // Disable HealthyPanicThreshold
  3.         HealthyPanicThreshold: &envoy_type.Percent{
  4.             Value: 0,
  5.         },
  6. }

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

3.1. 关于变量和常量的注释应描述其内容而非其目的

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

  1. const randomNumber = 6 // determined from an unbiased die

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

  1. const (
  2.     StatusContinue           = 100 // RFC 7231, 6.2.1
  3.     StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2
  4.     StatusProcessing         = 102 // RFC 2518, 10.1
  6.     StatusOK                 = 200 // RFC 7231, 6.3.1

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

贴士: 对于没有初始值的变量，注释应描述谁负责初始化此变量。

  1. // sizeCalculationDisabled indicates whether it is safe
  2. // to calculate Types' widths and alignments. See dowidth.
  3. var sizeCalculationDisabled bool

这里的注释让读者知道 dowidth 函数负责维护 sizeCalculationDisabled 的状态。

隐藏在众目睽睽下 这个提示来自Kate Gregory[3]。有时你会发现一个更好的变量名称隐藏在注释中。

  1. // registry of SQL drivers
  2. var registry = make(map[string]*sql.Driver)

注释是由作者添加的，因为 registry 没有充分解释其目的 - 它是一个注册表，但注册的是什么？

通过将变量重命名为 sqlDrivers，现在可以清楚地知道此变量的目的是保存SQL驱动程序。

  1. var sqlDrivers = make(map[string]*sql.Driver)

之前的注释就是多余的，可以删除。

3.2. 公共符号始终要注释

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

以下是 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)

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

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

这是 io 包中的一个例子

  1. // LimitReader returns a Reader that reads from r
  2. // but stops with EOF after n bytes.
  3. // The underlying implementation is a *LimitedReader.
  4. func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} }
  6. // A LimitedReader reads from R but limits the amount of
  7. // data returned to just N bytes. Each call to Read
  8. // updates N to reflect the new amount remaining.
  9. // Read returns EOF when N <= 0 or when the underlying R returns EOF.
  10. type LimitedReader struct {
  11.     R Reader // underlying reader
  12.     N int64  // max bytes remaining
  13. }
  15. func (l *LimitedReader) Read(p []byte) (n int, err error) {
  16.     if l.N <= 0 {
  17.         return 0, EOF
  18.     }
  19.     if int64(len(p)) > l.N {
  20.         p = p[0:l.N]
  21.     }
  22.     n, err = l.R.Read(p)
  23.     l.N -= int64(n)
  24.     return
  25. }

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

贴士: 在编写函数之前，请编写描述函数的注释。 如果你发现很难写出注释，那么这就表明你将要编写的代码很难理解。

3.2.1. 不要注释不好的代码，将它重写

Don’t comment bad code — rewrite it — Brian Kernighan

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

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

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

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

3.2.2. 与其注释一段代码，不如重构它

Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer. 好的代码是最好的文档。 在即将添加注释时，请问下自己，“如何改进代码以便不需要此注释？’ 改进代码使其更清晰。 — Steve McConnell

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

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