golang 注释规范

孟帅
2022-01-15 20:11:25
Go
Go goland

注释的意义

注释可以帮我们很好的完成文档的工作，写得好的注释可以方便我们以后的维护。

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

下面从包注释、结构体（接口）注释、函数（方法）注释、代码逻辑注释以及注释规范方面进行说明。

包注释

每个包都应该有一个包注释，一个位于 package 子句之前行注释

包注释应该包含下面基本信息

// Package  ${package_name}
// @Description  ${todo}
// @Author  MengShuai
package mian

结构（接口）注释

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

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

函数（方法）注释

每个函数，或者方法（结构体或者接口下的函数称为方法）都应该有注释说明

函数的注释应该包括三个方面

//
//  @Title  ${todo}
//  @Description  ${todo}
//  @Author  MengShuai <133814250@qq.com>
//  @Param   ${params}
//  @Return  ${return_types}
//

代码逻辑注释

每个代码块都要添加单行注释

注视使用 TODO 开始详细如下

// TODO  代码块的执行解释
if   userAge < 18 {
 
}

注释要求

统一使用中文注释，对于中英文字符之间严格使用空格分隔，这个不仅仅是中文和英文之间，英文和中文标点之间也都要使用空格分隔

全部使用单行注释，禁止使用多行注释

和代码的规范一样，单行注释不要过长，禁止超过 120 字符。

缩进和折行

缩进必须使用 gofmt 工具格式化

折行方面，一行最长不超过 120 个字符，超过的请使用换行展示，尽量保持格式优雅

括号和空格

括号和空格方面，也可以直接使用 gofmt 工具格式化（go 会强制左大括号不换行，换行会报语法错误），所有的运算符和操作数之间要留空格。

import 规范

// 单行引入
import  "fmt"

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

// 使用绝对路径，避免相对路径如 ../encoding/json

import (
     "strings"
     "fmt"
)

goanno

可以通过goland或者idea的插件市场通过搜索goanno下载。

也可以直接通过如下的网址下载release包，通过本地安装插件安装。

https://plugins.jetbrains.com/plugin/14988-goanno

https://github.com/loveinsky100/goanno

完美支持goland的函数注释，包括interface/普通函数/函数接受者/多个出参

以下是一些自用注释，可以参考

Normal Method

// @Title ${todo}

// @Description ${todo}

// @Author Ms <133814250@qq.com>

// @Param ${params}

// @Return ${return_types}

lnterface

// ${interface_name}

// @Description ${todo}

lnterface Method

// @Title ${todo}

// @Description ${todo}

// @Author Ms <133814250@qq.com>

// @Param ${params}

// @Return ${return_types}

Struct

// ${todo}

Struct Field

// ${todo}

Package

// @Link https://github.com/bufanyun/hotgo

// @Author Ms <133814250@qq.com>

// @License https://github.com/bufanyun/hotgo/blob/master/LICENSE

Other

// TODO ${todo}

无论从事什么行业，只要做好两件事就够了，一个是你的专业、一个是你的人品，专业决定了你的存在，人品决定了你的人脉，剩下的就是坚持，用善良專業和真诚赢取更多的信任。

上一篇： golang常用数据解析
下一篇： centos使用docker安装kafka

最新评论
总共0条评论

golang 注释规范

热门标签

置顶推荐

最新评论