5.3. 注释

优质

小牛编辑

117浏览

2023-12-01

5.3. 注释

Go支持C语言风格的/* */块注释，也支持C＋＋风格的//行注释。当然，行注释更通用，块注释主要用于针对包的详细说明或者屏蔽大块的代码。

程序 - 也是网页服务器 - godoc 处理 Go 的源代码，从中提取包的文档。顶层声明前的注解，如无空行相隔，和声明一起提取作为条目的解释文字。这些注解的性质和风格决定着 godoc 产生的文档的质量。

每个包都应有一个包注解，即 package 前的块注解。对多个文件的包，包注解只需出现在一个文件中，随便哪个。包注解应该介绍此包，并作为一个整体提供此包的对应信息。它首先出现在 godoc 页面，来安排好后续的详细文档

  /*
      The regexp package 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

包如果简单，注释可以简短。

  // The path package implements utility routines for
  // manipulating slash-separated filename paths.

注解不需多余排版如星星横幅等。生成的结果呈现时可能不是等宽字体，所以不要靠空格对齐， godoc，类似 gofmt 照管这些。最后，注解是不加解释的文本，HTML和其他例如 this 会原样照搬，所以应避免使用。

在包里，紧跟顶层声明前的注解作为此声明的文注解，程序中每个导出（大写）的名字都应该有文注解。

文注解最好是完整的句子。首句应该以声明的名字开始的一句话的总结。

  // Compile parses a regular expression and returns, if successful, a Regexp
  // object that can be used to match against text.
  func Compile(str string) (regexp *Regexp, error os.Error) {

Go 的声明句法允许编组。单一的文注解可以引出一组相联的常量或变量。因为整组声明一起展现，注解可以很粗略：

  // Error codes returned by failures to parse an expression.
  var (
      ErrInternal      = os.NewError("internal error")
      ErrUnmatchedLpar = os.NewError("unmatched '('")
      ErrUnmatchedRpar = os.NewError("unmatched ')'")
      ...
  )

对于私有名称，编组也可以指出它们之间的联系，例如一系列的变量由一个互斥保护。

  var (
      countLock   sync.Mutex
      inputCount  uint32
      outputCount uint32
      errorCount  uint32
  )