接上篇

二. 注释

注释虽然写起来很痛苦, 但对保证代码可读性至关重要。良好的代码注释可以帮助同事更好理解你的代码，提升工作效率。下面的规则描述了如何注释以及在哪儿注释。

有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字.

你写的注释是给代码读者看的, 也就是下一个需要理解你的代码的人。

• 必须 ：脚本都需要添加注释: 表明脚本的作用, 参数的含义, 预期的数据, 输入参数的含义
• 建议 ：方法上建议添加注释, 标注方法的作用
• 建议 ：有步骤执行顺序的代码, 各个顺序关键节点, 建议添加注释
• 建议 ：if, switch等分支判断的时候, 建议添加注释便于理解

1. 注释风格

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

2. 包注释

// 请填写文件描述

package ${GO_PACKAGE_NAME}

3. 结构体（接口）注释

// User   用户对象，定义了用户的基础信息
type User struct{

    Username  string // 用户名

    Email     string // 邮箱

}

4. 函数（方法）注释

// 函数的详细描述

// 函数的详细描述2

func (r *RiskCase) GetRiskCase(ctx context.Context)

5. 代码逻辑注释

// 代码块的执行解释

// 执行解释2

if   userAge < 18 {

}

三. 其他规范

1 . Error命名规范

使用MixedCaps或者mixedCaps的形式, 以Err开头

2 . import 规范

• 单行引入

import "fmt"

• 多包引入，每包独占一行

使用绝对路径，避免相对路径如

import (

     "strings"

     "fmt"
)

• 如果程序包名称与导入路径的最后一个元素不匹配，则必须使用导入别名。
• 在所有其他情况下，除非导入之间有直接冲突，否则应避免导入别名。