golang 注释规范
0 / 0 / 创建于 3年前 /
wangchunbo 的个人博客
[Golang 注释规范]
注释的意义[#]
- 注释可以帮我们很好的完成文档的工作，写得好的注释可以方便我们以后的维护。
- /**/ 的块注释和 // 的单行注释两种注释风格， 在我们的项目中为了风格的统一，全部使用单行注释，注释的质量决定了生成的文档的质量。
- 下面从包注释、结构体（接口）注释、函数（方法）注释、代码逻辑注释以及注释规范方面进行说明。
包注释[#]
- 每个包都应该有一个包注释，一个位于 package 子句之前行注释
- 包注释应该包含下面基本信息
Copy
// @Title 请填写文件名称（需要改）
// @Description 请填写文件描述（需要改）
// @Author 请填写自己的真是姓名（需要改） ${DATE} ${TIME}
// @Update 请填写自己的真是姓名（需要改） ${DATE} ${TIME}
package ${GO_PACKAGE_NAME}
结构（接口）注释
每个自定义的结构体或者接口都应该有注释说明，该注释对结构进行简要介绍，放在结构体定义的前一行，格式为： 结构体名， 结构体说明。同时结构体内的每个成员变量都要有说明，该说明放在成员变量的后面（注意对齐），实例如下：
type User struct{
Username string // 用户名
Email string // 邮箱
}函数（方法）注释
- 每个函数，或者方法（结构体或者接口下的函数称为方法）都应该有注释说明
- 函数的注释应该包括三个方面
// @description 函数的详细描述
// @auth 作者 时间（2019/6/18 10:57 ）
// @param 输入参数名 参数类型 "解释"
// @return 返回参数名 参数类型 "解释"` 代码逻辑注释
- 每个代码块都要添加单行注释
- 注视使用 TODO 开始 详细如下
if userAge < 18 {
}注释要求
- 统一使用中文注释，对于中英文字符之间严格使用空格分隔， 这个不仅仅是中文和英文之间，英文和中文标点之间也都要使用空格分隔
- 全部使用单行注释，禁止使用多行注释
- 和代码的规范一样，单行注释不要过长，禁止超过 120 字符。
缩进和折行
- 缩进必须使用
gofmt工具格式化 - 折行方面，一行最长不超过 120 个字符，超过的请使用换行展示，尽量保持格式优雅
括号和空格
括号和空格方面，也可以直接使用 gofmt 工具格式化（go 会强制左大括号不换行，换行会报语法错误），所有的运算符和操作数之间要留空格。
import 规范
import "fmt"`
Copy
// 多包引入，每包独占一行
// 使用绝对路径，避免相对路径如 ../encoding/json
import (
"strings"
"fmt"
)本作品采用《CC 协议》，转载必须注明作者和本文链接
关于 LearnKu
粤公网安备 44030502004330号