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

文章目录 文档目标注释规范总体原则文件注释结构体及接口注释函数及方法注释import规范 注释模板配置goLand文件注释模板配置goLand方法修改注释模板配置Goanno方法、接口、结构体注释模板配置

文档目标

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

注释规范 总体原则 注释使用单个英文半角空格作为分隔符，避免注释中空格数量及格式混乱。全部使用单行注释，禁止使用多行注释，// 后紧跟一个英文半角空格 文件注释

每个文件都要有一个注释，位于 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文件注释模板配置 goland 菜单路径： File->Settings->Editor->File and Code Templates 打开如下对话框

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

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

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

配置完成 点击 Apply OK 按钮。新建一个go文件自动追加了作者及创建时间
goLand方法修改注释模板配置 goland 菜单路径： File->Settings->Editor->File and Code Templates 打开如下对话框。
点”+”选择Live Template,新建方法修改注释模板，配置内容如下

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

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

点击 Edit variables 绑定变量值如下

date方法可以传入参数指定日期格式 如下：date(“Y-MM-dd H:mm:ss”) 2021-10-01 14:07:50

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

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

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

安装Goanno插件，如下

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

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

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

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