在编写 Go 语言程序时,为一些关键代码加上注释是非常有必要的。注释既方便我们自己日后回顾修改,也方便团队里的其他成员快速看懂代码逻辑。
注释的内容是写给我们人看的,而不是给计算机看的。Go 编译器在编译代码时会直接忽略所有注释,不会影响程序的运行结果和执行速度。在 Go 语言中,注释主要分为 2 种:一种是 “单行注释”,另一种是 “多行注释”。
Go 单行注释
在 Go 语言中,当注释内容比较简短时,我们可以使用双斜杠 // 来编写单行注释。从 // 开始一直到当前行末尾的所有文字,都会被编译器当作注释忽略掉。
语法:
// 单行注释内容说明:
单行注释既可以单独占一行放在代码的正上方,也可以跟在某行代码的末尾,用来说明代码的作用或变量的含义。在实际开发中,并不是每一行简单代码都要写注释,我们一般只对关键逻辑添加说明。
示例 1:使用单行注释
package main
import "fmt"
func main() {
// 定义年龄变量并赋初值
age := 20 // 单位:岁
// fmt.Println(100)
fmt.Println(age)
}运行结果如下。
20分析:
上面代码一共写了 3 处单行注释:第 1 处单独占一行放在 age := 20 的正上方;第 2 处放在 age := 20 的行尾;第 3 处则是使用 // 把 fmt.Println(100) 这行代码注释掉了。
从运行结果可以看到,被 // 注释掉的那行打印语句并没有执行,屏幕只输出了 20。这种通过注释临时屏蔽某行代码的做法,在我们平时排查错误、调试程序时非常实用。
提示: 在 VSCode 或 GoLand 中,如果我们想快速把选中的一行或多行代码变成单行注释,只需要按下快捷键(Ctrl + /,macOS 按 Cmd + /)。再按一次相同的快捷键,就能取消注释。
Go 多行注释
在 Go 语言中,当说明文字比较多、一行写不下,或者调试代码时想要一次性屏蔽一大段代码,我们可以使用多行注释(也叫做 “块注释”)。
语法:
/*
多行注释内容
多行注释内容
*/说明:
多行注释以 /* 开头,并以 */ 结尾。凡是夹在 /* 和 */ 中间的所有内容,不管跨越多少行,都会被编译器整体忽略。
示例 2:使用多行注释
package main
import "fmt"
/*
这是一个演示多行注释的程序
主函数中只打印最后一个数字
*/
func main() {
/*
fmt.Println(10)
fmt.Println(20)
*/
fmt.Println(30) // 只执行这一行打印语句
}运行结果如下。
30分析:
我们在 func main() 上方使用 /* ... */ 写了一段跨两行的程序说明,接着又在函数内部使用 /* ... */ 把前两行打印语句包裹了起来,因此最终只有最后一行 fmt.Println(30) 会执行并输出 30。
注意: 多行注释 /* ... */ 不允许嵌套使用。如果在里面再写一对 /* ... */,外层的 /* 会和内层的第一个 */ 提前配对,导致后面的代码漏在外面而报错。平时调试屏蔽多行代码,直接按快捷键(Ctrl + /)批量添加 // 注释会更省心。
Go 注释的使用规范
在实际项目开发中,为了让代码注释更加清晰规范,建议小伙伴们养成以下 3 个习惯:
- 优先使用单行注释:在 Go 官方标准库和实际项目中,日常说明哪怕有连续好几行,我们也优先使用
//单行注释。多行注释/* ... */一般只用于包顶部的大段说明或临时屏蔽代码。 - 双斜杠后留一个空格:在编写
//单行注释时,//与后面的文字之间建议留出一个半角空格,阅读起来更加清爽。在编辑器中保存.go文件时,格式化工具通常也会自动补齐这个空格。 - 修改代码同步更新注释:当我们修改了某段代码的逻辑时,记得同步更新旁边的注释说明,避免注释文字与实际代码对不上。
此外,Go 语言社区还有一个很实用的 “文档注释” 约定:在定义公开的常量或函数时,紧贴在声明行的正上方写一句以 “该名称开头” 的 // 注释。
下面以常量 MaxCount 和一个自定义函数 SayHello() 为例。关于自定义函数的具体写法,后面章节会详细介绍:
// MaxCount 表示最大重试次数
const MaxCount = 3
// SayHello 打印欢迎提示信息
func SayHello() {
fmt.Println("Hello, Go!")
}按照这种格式写好注释后,以后我们在其他地方使用 MaxCount 或调用 SayHello() 时,只要把鼠标悬停在它们的名字上,编辑器就会自动弹出提示卡片展示这段说明。
需要留意一点:文档注释必须紧贴在声明行的正上方,中间不能留空行,否则编辑器和文档工具无法将它识别为对应的说明。
