Golang注视规范

注释的意义

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

包注释

• 每个包都应该有一个包注释，一个位于package子句之前行注释
• 包注释应该包含下面基本信息

// @Title  文件名称
// @Description  文件描述
// @Author  作者名称 (时间 格式是2019/3/26  19:53)
// @Update  修改者名称 (时间 格式是2019/3/26  19:53)

结构（接口）注释

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

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

函数（方法）注释

• 每个函数，或者方法（结构体或者接口下的函数称为方法）都应该有注释说明
• 函数的注释应该包括三个方面

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

代码逻辑注释

对于一些关键位置的代码逻辑，或者局部较为复杂的逻辑，需要有相应的逻辑说明，方便其他开发者阅读该段代码，实例如下：

// 从 Redis 中批量读取属性，对于没有读取到的 id ， 记录到一个数组里面，准备从 DB 中读取
xxxxx
xxxxxxx
xxxxxxx

注释风格

统一使用中文注释，对于中英文字符之间严格使用空格分隔， 这个不仅仅是中文和英文之间，英文和中文标点之间也都要使用空格分隔，例如：
// 从 Redis 中批量读取属性，对于没有读取到的 id ， 记录到一个数组里面，准备从 DB 中读取
1
上面 Redis 、 id 、 DB 和其他中文字符之间都是用了空格分隔。

• 全部使用单行注释，禁止使用多行注释（代码规范就是要独裁，要定死，让我们不用纠结应该用哪个）；
• 和代码的规范一样，单行注释不要过长，禁止超过 120 字符。

3 代码风格
3.1 缩进和折行
缩进直接使用 gofmt 工具格式化即可（gofmt 应该是使用 tab 缩进的）；
折行方面，一行最长不超过120个字符，超过的请使用换行展示，尽量保持格式优雅。
3.2 括号和空格
括号和空格方面，也可以直接使用 gofmt 工具格式化（go 会强制左大括号不换行，换行会报语法错误），所有的运算符和操作数之间要留空格。

// 正确的方式
if a > 0 {

}

// 错误的方式
if a>0 // a ，0 和 > 之间应该空格
{ // 左大括号不可以换行，会报语法错误

}

import 规范

// 单行引入
import  "fmt"

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