文档目标

良好的注释对项目后续的开发维护工作十分必要。本文档旨在明确项目开发过程中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} 
  1. 点击Files,选择Go File 配置内容如下

在这里插入图片描述

  1. 配置完成 点击 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 为自定义快捷键,可按照自己习惯定义。

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

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

在这里插入图片描述

  1. 在代码中方法上 输入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

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