go语言的注释编码规范是什么

2023-05-14 20:05:57 规范 编码 注释

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

go语言的注释编码规范是什么

教程操作环境:windows7系统、Go 1.18版本、Dell G3电脑。

注释的意义

  • 注释可以帮我们很好的完成文档的工作,写得好的注释可以方便我们以后的维护。

  • 的块注释和 // 的单行注释两种注释风格, 在我们的项目中为了风格的统一,全部使用单行注释,注释的质量决定了生成的文档的质量。

注释规范

  • 所有导出对象都需要注释说明其用途;非导出对象根据情况进行注释。

  • 如果对象可数且无明确指定数量的情况下,一律使用单数形式和一般进行时描述;否则使用复数形式。

  • 包、函数、方法和类型的注释说明都是一个完整的句子。

  • 句子类型的注释首字母均需大写;短语类型的注释首字母需小写。

  • 注释的单行长度不能超过80个字符。

1、包级别

包级别的注释就是对包的介绍,只需在同个包的任一源文件中说明即可有效。【相关推荐:Go视频教程、编程教学】

  • 每个包都应该有一个包注释,一个位于 package 子句之前行注释

  • 包注释应该包含下面基本信息

// @Title  请填写文件名称(需要改)
// @Description  请填写文件描述(需要改)
// @Author  请填写自己的真是姓名(需要改)  ${DATE} ${TIME}
// @Update  请填写自己的真是姓名(需要改)  ${DATE} ${TIME}
package ${GO_PACKAGE_NAME}

2、结构(接口)注释

每个自定义的结构体或者接口都应该有注释说明,该注释对结构进行简要介绍,放在结构体定义的前一行,格式为: 结构体名, 结构体说明。同时结构体内的每个成员变量都要有说明,该说明放在成员变量的后面(注意对齐),实例如下:

// User   用户对象,定义了用户的基础信息
type User struct{
    Username  string // 用户名
    Email     string // 邮箱
}

3、函数(方法)注释

  • 每个函数,或者方法(结构体或者接口下的函数称为方法)都应该有注释说明

  • 函数的注释应该包括三个方面

// @title    函数名称
// @description   函数的详细描述
// @auth      作者             时间(2019/6/18   10:57 )
// @param     输入参数名        参数类型         "解释"
// @return    返回参数名        参数类型         "解释"

4、代码逻辑注释

  • 每个代码块都要添加单行注释

  • 注视使用 TODO 开始 详细如下

// TODO  代码块的执行解释
if   userAge < 18 {

}

其它说明

  • 当某个部分等待完成时,可用 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)

以上就是go语言的注释编码规范是什么的详细内容,更多请关注其它相关文章!

相关文章