这是我参与「第三届青训营 -后端场」笔记创作活动的第5篇笔记
因为项目即将开始，很多东西都需要一个规范，注释也是，提高代码的可读性。之前上课也学了一些代码规范，今天就来把注释这个方面的总结一下。
注释分为：包注释和代码注释
1 包注释
- 位于 package 之前，如果一个包有多个文件，只需要在一个文件中编写即可。
- 包注释格式按照：简介，创建人，创建时间 来写。
//Copyright: Go作者XXX 版权所有。
// @Description 这是一个userinfo包的例子注释；
// @Author 创建人XXX；
// @Update 20220512 （创建/修改时间）；
package userinfo
//每一行结尾如果需要加标点就加个标点，啥标点都行，
//如果只是一句话话话话话话话话话话话话话话话话话话话话话话话话话话
//话太多了需要换行，就不用加标点。
//最上面一行如果有版权声明要隔开；
//注释不要写太长，一行不超过80个字符，应该没有那么严格，自己判断一下就行吧[笑哭]。
/*
也可以
用这个 杠星 的格式
进行多行注释。
*/
VSCode查看注释：（奇怪为啥不按我的排列换行，枯了）
- 如果是特别复杂的包，可以在包下单独创建 doc.go 文件说明：
a. Go doc命令，在命令行中查看代码注释
先在项目下新建doc.go文档，注意名字必须是这个doc.go。然后只写一句导包：package XXX，最后在这句代码在上面写注释就行了。
执行go doc 命令后：
b. godoc命令，在生成的网页中查看项目注释文档（与 go doc 相比中间没有空格）
在项目文件夹下使用命令：
- godoc -http=:6060
（这个结果表示已经正常启动，如果不能正常启动说明需要安装godoc）
- 再在浏览器中打开链接：http://127.0.0.1:6060/pkg/项目名/包名
就可以看见刚才编写的注释生成的文档：
文档里面还能点击进去查看函数代码，不得不说是真的香：
2 代码注释
- 注释应该解释代码的作用、不同情况返回什么结果、以及如何实现、为何要这样实现。
- 所有可导出的变量或函数等都需要注释说明其用途；非导出对象根据情况进行注释。例：
//TopicData是页面数据结构体，其中包括话题页面信息；
//Code和Msg表示业务err定义，Code为0表示成功，非0表示函数异常。
//TopicDatas是成功返回时传出的话题数据。
type TopicData struct {
Code int64 //状态码
Msg string //错误信息
TopicDatas interface{} //话题数据
}
//Mkdir使用传入的名称name和perm创建一个新目录。
//如果出错，它将是*PathError类型。
func Mkdir(name string, perm FileMode) error {
}
- 如果注释中写了类似代码的语句：
/*
var num1 int
AddNum将两个数字计算后返回结果sum
var num2 int
for i:=0;i<5;i++{
num1 = num2*5
}
*/
func AddNum(num1 int, num2 int) (sum int) {
sum = num1 + num2
return
}
VSCode效果：会自动识别到类似于代码的东东。
- 但是要注意注释中的代码要换行和缩进，代码要比文字解释多缩进一格。
①如果全在缩进在一列就不行了：
/*
var num1 int
AddNum将两个数字计算后返回结果sum
var num2 int
for i:=0;i<5;i++{
num1 = num2*5
}
*/
func AddNum(num1 int, num2 int) (sum int) {
sum = num1 + num2
return
}
②如果是这样：解释比代码多缩进一格，也不行
/*
var num1 int
var num2 int
AddNum将两个数字相加然后返回结果sum
var num1 int
var num2 int
AddNum(num1, num2) sum
*/
func AddNum(num1 int, num2 int) (sum int) {
sum = num1 + num2
return
}
总结：
- 最重要的其实就是描述清楚代码就行了
- 代码是最好的注释
特别注释
- TODO：提醒维护人员此部分代码待完成
- FIXME：提醒维护人员此处有BUG待修复
- NOTE：维护人员要关注的一些问题说明
——THE END——
