GO 注释

1. 注释规范

  • 所有导出对象都需要注释说明其用途,非导出对象根据情况进行注释。
  • 如果对象可数且无明确指定数量的情况下,一律使用单数形式和一般进行时描述;否则使用复数形式。
  • 包、函数、方法二号类型的注释说明都是一个完整的句子。
  • 句子类型的注释首字母均需要大写,短句类型的注释首字母需小写。
  • 注释的单行长度不能超过 80 个字符,禁止超过 120 个字符。

1.1 包级别

  • 包级别的注释就是对包的介绍,只需再同个包的任一源文件中说明即可有效。
  • 对于 mian 包,一般只有一行简短的注释用于说明报的用途,且以项目名称开头:
// Gogs (Go Git Service) is a painless self-hosted Git Service.
package main
  • 对于一个复杂项目的子包,一般情况下不需要包级别注释,除非时代表某个特定功能的模块。
  • 对于简单的非 main 包,也可以一行注释概括。
  • 对于相对功能复杂的非 main 包,一般都会增加一些使用示例或基本说明,且以 Package <name> 开头:
/*
  Package regexp 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
  • 特别复杂的包说明,也可以单独创建 doc.go 文件来加以说明

1.2 结构、接口及其它类型

  • 类型的定义一般都以单数形式描述:
// Request represents a request to run a command.
  type Requeststruct{...
  • 如果为接口,则一般以以下形式描述:
// FileInfo is the interface that describes a file and is returned by Stat and Lstat.
  type FileInfointerface{...

1.3 函数与方法

  • 函数与方法的注释需要以函数或方法的名称作为开头:
// Post returns *BeegoHttpRequest with POST method.
  • 如果一句话不足以说明全部问题,则可换行继续进行更加细致的描述:
// Copy copies file from source to target path.
// It returns false and error when error occurs in underlying function calls.
  • 若函数或方法为判断类型(返回值主要为 bool 类型),则以 <name> returns true if 开头:
// HasPrefix returns true if name has any string in given slice as prefix.
  func HasPrefix(name string, prefixes []string)bool{...

1.4 其他说明

  • 当某个部分等待完成时,可用 TODO: 开头的注释来提醒维护人员。
  • 当某个部分存在已知问题进行需要修复或改进时,可用 FIXME: 开头的注释来提醒维护人员。
  • 当某个变量或函数强烈建议不要再使用时,可用 Deprecated: 开头的注释来提醒维护人员。
  • 当需要特别说明某个问题时,可用 NOTE: 开头注释:
// NOTE: os.Chmod and os.Chtimes don't recognize symbolic link,
// which will lead "no such file or directory" error.
return os.Symlink(target, dest)
点赞

发表评论

电子邮件地址不会被公开。必填项已用 * 标注