公共符号始终要注释
发布者:admin 发表于:417天前 阅读数:563 评论:0

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)

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

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

这是 io 包中的一个例子

// LimitReader returns a Reader that reads from r
// but stops with EOF after n bytes.
// The underlying implementation is a *LimitedReader.
func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} }

// A LimitedReader reads from R but limits the amount of
// data returned to just N bytes. Each call to Read
// updates N to reflect the new amount remaining.
// Read returns EOF when N <= 0 or when the underlying R returns EOF.
type LimitedReader struct {
    R Reader // underlying reader
    N int64  // max bytes remaining
}

func (l *LimitedReader) Read(p []byte) (n int, err error) {
    if l.N <= 0 {
        return 0, EOF
    }
    if int64(len(p)) > l.N {
        p = p[0:l.N]
    }
    n, err = l.R.Read(p)
    l.N -= int64(n)
    return
}

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

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

不要注释不好的代码,将它重写

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

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

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

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

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

与其注释一段代码,不如重构它

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

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

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