• 3.2. 公共符号始终要注释

    3.2. 公共符号始终要注释

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

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

    • 任何既不明显也不简短的公共功能必须予以注释。
    • 无论长度或复杂程度如何,对库中的任何函数都必须进行注释```golangpackage 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} }
    5. // A LimitedReader reads from R but limits the amount of
    6. // data returned to just N bytes. Each call to Read
    7. // updates N to reflect the new amount remaining.
    8. // Read returns EOF when N <= 0 or when the underlying R returns EOF.
    9. type LimitedReader struct {
    10. R Reader // underlying reader
    11. N int64 // max bytes remaining
    12. }
    13. func (l *LimitedReader) Read(p []byte) (n int, err error) {
    14. if l.N <= 0 {
    15. return 0, EOF
    16. }
    17. if int64(len(p)) > l.N {
    18. p = p[0:l.N]
    19. }
    20. n, err = l.R.Read(p)
    21. l.N -= int64(n)
    22. return
    23. }

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

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