你好

第17节 规范


❤️💕💕记录sealosopen in new window开源项目的学习过程。k8s,docker和云原生的学习open in new window。Myblog:http://nsddd.topopen in new window

[TOC]

注释规范

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

包级别

  • 包级别的注释就是对包的介绍，只需在同个包的任一源文件中说明即可有效。

  • 对于 main 包，一般只有一行简短的注释用以说明包的用途，且以项目名称开头：

      // 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.goopen in new window 文件来加以说明。

结构、接口及其它类型

  • 类型的定义一般都以单数形式描述：

    // Request represents a request to run a command.  type Request struct { ...

  • 如果为接口，则一般以以下形式描述：

    // FileInfo is the interface that describes a file and is returned by Stat and Lstat.  type FileInfo interface { ...

函数与方法

  • 函数与方法的注释需以函数或方法的名称作为开头：

    // 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 { ... }

其它说明

  • 当某个部分等待完成时，可用 TODO: 开头的注释来提醒维护人员。

  • 当某个部分存在已知问题进行需要修复或改进时，可用 FIXME: 开头的注释来提醒维护人员。

  • 当需要特别说明某个问题时，可用 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)

包括什么

  • 该kubernetes软件包包含用于访问 Kubernetes API 的客户端集。
  • 该discovery包用于发现 Kubernetes API 服务器支持的 API。
  • 该dynamic软件包包含一个动态客户端，可以对任意 Kubernetes API 对象执行通用操作。
  • 这些plugin/pkg/client/auth软件包包含可选的身份验证插件，用于从外部来源获取凭证。
  • 该transport包用于设置身份验证和启动连接。
  • 该tools/cache包对于编写控制器很有用。

命名规则

  • 整个应用或包的主入口文件应当是 main.go 或与应用名称简写相同。例如：Gogs 的主入口文件名为 gogs.go。
  • 若函数或方法为判断类型（返回值主要为 bool 类型），则名称应以 Has, Is, Can 或 Allow 等判断性动词开头：
  • 常量均需使用全部大写字母组成，并使用下划线分词：
  • 如果是枚举类型的常量，需要先创建相应类型
  • 如果模块的功能较为复杂、常量名称容易混淆的情况下，为了更好地区分枚举类型，可以使用完整的前缀
  • 变量命名基本上遵循相应的英文表达或简写。
  • 在相对简单的环境（对象数量少、针对性强）中，可以将一些名称由完整单词简写为单个字母，例如：
    • user 可以简写为 u
    • userID 可以简写 uid
  • 若变量类型为 bool 类型，则名称应以 Has, Is, Can 或 Allow 开头

测试用例

使用示例

  • 为辅助包书写使用示例的时，文件名均命名为 example_test.go。
  • 测试用例的函数名称必须以 Test_ 开头，例如：Test_Logger。
  • 如果为方法书写测试用例，则需要以 Text_<Struct>_<Method> 的形式命名，例如：Test_Macaron_Run。

END 链接