Go语言注释规范

1.注释规范

包注释

包注释是对包的介绍，每个包都至少有一个包注释，在同一个包下，任一一个源文件中注释即可，放置在package之前，来简短描述这个包的功能

例子：

// Package analyze 用于分析在接入层获取的接口
package analyze

文件注释

每个文件都应有一个文件注释，放置在package之后，需要包含文件名称，文件描述，文件作者及其时间，更新作者及其时间

例子：

package 包名称

// @Title        文件名称
// @Description  文件描述
// @Create       创建作者 日期 时间
// @Update       更新作者 日期 时间

结构体注释和接口注释

每个结构体或接口都应有注释，在结构体或接口定义上面，需要有一个对整个结构体或接口的简要介绍，结构体或接口内的每个成员变量也需要有注释

例子：

// User defines user login info
type User struct {
    UserName string // user's name
    Password string // user's password
}

// IUser defines user function
type IUser interface {
    Login()  // user login into the system
    Logout() // user logout the system
}

函数和方法的注释

每个函数或方法都应有注释，需要包含函数或方法名称、函数或方法描述、函数或方法的创建作者及其创建时间、输入参数及其参数类型和解释、返回参数及其参数类型和解释

例子：

// 函数或方法名称
// @Description        函数或方法描述
// @Create             作者 日期 时间
// @Param              输入参数名 参数类型 解释
// @Return             返回参数名 参数类型 解释

如果涉及到函数或方法的变更，需要写明修改作者、修改日期和时间、修改的功能描述

// @Modified           作者 日期 时间
// @Modify description 修改的功能描述

代码逻辑注释

每个代码块都需要添加注释，特别是比较复杂的逻辑：

// todo
if age == 18 {
    ...
}

2.Goland注释相关配置

包注释和文件注释配置

Goland->Settings->Editor->File and Code Templates->Go File

替换为如下配置：

// 
package ${GO_PACKAGE_NAME}

// @Title        ${FILE_NAME}
// @Description  
// @Create       yourname ${YEAR}-${MONTH}-${DAY} ${TIME}
// @Update       yourname ${YEAR}-${MONTH}-${DAY} ${TIME}

Goanno插件

1、安装Goanno插件

2、修改默认配置

1️⃣ 函数注释、方法注释

// ${function_name}
// @Description ${todo}
// @Create         yourname ${date} 
// @Param          ${param_name} ${param_type}
// @Return          ${ret_name_type}

2️⃣ Struct 配置

// ${struct_name} 

3️⃣ 接口注释

// ${interface_name}