注释的意义

  • 注释可以帮我们很好的完成文档的工作,写得好的注释可以方便我们以后的维护。
  • /**/ 的块注释和 // 的单行注释两种注释风格, 在我们的项目中为了风格的统一,全部使用单行注释,注释的质量决定了生成的文档的质量。
  • 下面从包注释、结构体(接口)注释、函数(方法)注释、代码逻辑注释以及注释规范方面进行说明。

包注释

  • 每个包都应该有一个包注释,一个位于package子句之前行注释
  • 包注释应该包含下面基本信息
// @Title  请填写文件名称(需要改)
// @Description  请填写文件描述(需要改)
// @Author  请填写自己的真是姓名(需要改)  ${DATE} ${TIME}
// @Update  请填写自己的真是姓名(需要改)  ${DATE} ${TIME}
package ${GO_PACKAGE_NAME}

结构(接口)注释

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

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

函数(方法)注释

  • 每个函数,或者方法(结构体或者接口下的函数称为方法)都应该有注释说明
  • 函数的注释应该包括三个方面
// @title    函数名称
// @description   函数的详细描述
// @auth      作者             时间(2019/6/18   10:57 )
// @param     输入参数名        参数类型         "解释"
// @return    返回参数名        参数类型         "解释"

代码逻辑注释

  • 每个代码块都要添加单行注释
  • 注视使用TODO 开始 详细如下
// TODO  代码块的执行解释
if   userAge < 18 {
     
}
注释要求
  • 统一使用中文注释,对于中英文字符之间严格使用空格分隔, 这个不仅仅是中文和英文之间,英文和中文标点之间也都要使用空格分隔
  • 全部使用单行注释,禁止使用多行注释
  • 和代码的规范一样,单行注释不要过长,禁止超过 120 字符。

缩进和折行

  • 缩进必须使用 gofmt 工具格式化
  • 折行方面,一行最长不超过120个字符,超过的请使用换行展示,尽量保持格式优雅

括号和空格

括号和空格方面,也可以直接使用 gofmt 工具格式化(go 会强制左大括号不换行,换行会报语法错误),所有的运算符和操作数之间要留空格。

import 规范

// 单行引入
import  "fmt"
// 多包引入,每包独占一行
// 使用绝对路径,避免相对路径如 ../encoding/json
import (
     "strings"
     "fmt"
)