Golang 注释规范

注释的意义#

  • 注释可以帮我们很好的完成文档的工作,写得好的注释可以方便我们以后的维护。
  • /**/ 的块注释和 // 的单行注释两种注释风格, 在我们的项目中为了风格的统一,全部使用单行注释,注释的质量决定了生成的文档的质量。
  • 下面从包注释、结构体(接口)注释、函数(方法)注释、代码逻辑注释以及注释规范方面进行说明。

包注释#

  • 每个包都应该有一个包注释,一个位于 package 子句之前行注释
  • 包注释应该包含下面基本信息
Copy
// @Title 请填写文件名称(需要改) // @Description 请填写文件描述(需要改) // @Author 请填写自己的真是姓名(需要改) ${DATE} ${TIME} // @Update 请填写自己的真是姓名(需要改) ${DATE} ${TIME} package ${GO_PACKAGE_NAME}

结构(接口)注释#

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

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

函数(方法)注释#

  • 每个函数,或者方法(结构体或者接口下的函数称为方法)都应该有注释说明
  • 函数的注释应该包括三个方面
Copy
// @title 函数名称 // @description 函数的详细描述 // @auth 作者 时间(2019/6/18 10:57 ) // @param 输入参数名 参数类型 "解释" // @return 返回参数名 参数类型 "解释"

代码逻辑注释#

  • 每个代码块都要添加单行注释
  • 注视使用 TODO 开始 详细如下
Copy
// TODO 代码块的执行解释 if userAge < 18 { }

注释要求#

  • 统一使用中文注释,对于中英文字符之间严格使用空格分隔, 这个不仅仅是中文和英文之间,英文和中文标点之间也都要使用空格分隔
  • 全部使用单行注释,禁止使用多行注释
  • 和代码的规范一样,单行注释不要过长,禁止超过 120 字符。

缩进和折行#

  • 缩进必须使用 gofmt 工具格式化
  • 折行方面,一行最长不超过 120 个字符,超过的请使用换行展示,尽量保持格式优雅

括号和空格#

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

import 规范#

Copy
// 单行引入 import "fmt"
Copy
// 多包引入,每包独占一行 // 使用绝对路径,避免相对路径如 ../encoding/json import ( "strings" "fmt" )
posted @   ZhiChao&  阅读(21251)  评论(0编辑  收藏  举报
点击右上角即可分享
微信分享提示
CONTENTS