Golang代码注释规范及goland代码注释模板配置

文档目标

良好的注释对项目后续的开发维护工作十分必要。本文档旨在明确项目开发过程中go代码的注释规范，并提供基于goland的注释模板设置指导。便于开发人员快速配置环境，高效、合规开展工作。

注释规范

总体原则

1. 注释使用单个英文半角空格作为分隔符，避免注释中空格数量及格式混乱。
2. 全部使用单行注释，禁止使用多行注释，// 后紧跟一个英文半角空格

文件注释

每个文件都要有一个注释，位于 package 之前,格式如下

// @Author eric 2021/10/22 16:23:00
package test

结构体及接口注释

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

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

函数及方法注释

每个函数，或者方法（结构体或者接口下的函数称为方法）都应该有注释说明。内容包括：创建人、创建时间、功能描述、修改人、修改时间、修改原因。其中修改时间、修改人、修改原因只有在方法逻辑有大调整时增加。其他小的语法改动等不需要增加。如果修改是为了修复某个bug，需要在修改原因中写明bug编号。每个函数，或者方法（结构体或者接口下的函数称为方法）都应该有注释说明。内容包括：创建人、创建时间、功能描述、修改人、修改时间、修改原因。其中修改时间、修改人、修改原因只有在方法逻辑有大调整时增加。其他小的语法改动等不需要增加。如果修改是为了修复某个bug，需要在修改原因中写明bug编号。

方法注释：
// @Title hello
// @Description 实现XXX功能
// @Author eirc 2021-10-22 17:14:47 
// @Param name
// @Return string
func(User) hello(name string) string{


方法修改注释:
// @Modified By eric 2021/10/22 17:20:00
// @Modify description  修复bug0001

方法内容超过30行的,或者有复杂/不易理解逻辑的，要在方法内按照逻辑增加注释说明。格式如下：

// 未成年情况执行如下逻辑
if   userAge < 18 {
……
}

import规范

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

注释模板配置

这里基于goLand开发工具进行配置，goLand工具本身提供了快捷注释的方式，但是不能够满足所有需求。goanno是一款goland注释插件，这里推荐二者结合使用。注释模板配置方式如下。

goLand文件注释模板配置

1. goland 菜单路径： File->Settings->Editor->File and Code Templates 打开如下对话框

如上图所示，点击“+“ 创建名为”head“的include条目，内容如下(由于goland中time只返回时分，后边追加:00 保证时间格式统一为时分秒)：

// @Author zhangxinmin ${DATE} ${TIME}:00 
package ${GO_PACKAGE_NAME} 

2. 点击Files，选择Go File 配置内容如下

3. 配置完成 点击 Apply OK 按钮。新建一个go文件自动追加了作者及创建时间
   

goLand方法修改注释模板配置

1. goland 菜单路径： File->Settings->Editor->File and Code Templates 打开如下对话框。
   点”+”选择Live Template,新建方法修改注释模板，配置内容如下

// @Modified By eric $date$ $time$:00 
// @Modify description $desc$ 

mmr 为自定义快捷键，可按照自己习惯定义。

2. 点击 Edit variables 绑定变量值如下
   
   date方法可以传入参数指定日期格式 如下：date(“Y-MM-dd H:mm:ss”) 2021-10-01 14:07:50

配置完成 依次点击OK Define Apply OK 按钮，Define 按钮对话框中选择Go

3. 在代码中方法上 输入mmr 回车即可自动显示注释模板。如下图

Goanno方法、接口、结构体注释模板配置

1. 安装Goanno插件，如下
   

2. 配置插件注释格式，Tools-> Goanno Settings
   

3. 配置内容如下，注意不要有多余行,每行后带空格

Normal Method 配置内容：
// @Title ${function_name} 
// @Description ${todo} 
// @Author zhangxinmin ${date} ${time} 
// @Param ${params} 
// @Return ${return_types} 

interface配置内容
// ${interface_name} 

Interface Method 配置内容
// @Title ${function_name} 
// @Description ${todo} 
// @Author zhangxinmin ${date} ${time} 
// @Param ${params} 
// @Return ${return_types} 

Struct配置内容
// ${struct_name} 

Struct Field  不做配置

配置完成点击submit

4. 验证注释 在方法、结构体、接口上 使用快捷键 ctrl +alt +/ mac系统使用control + commond + / 快捷键, 可自动生成注释 如下截图