Go 语言基础语法:注释
注释含义
好的注释能让我们更好地上手代码,方便后续的维护。
Go 语言提供了类似 C 语言风格的块注释/* */
和 C++ 风格的行注释 //
。行注释很常见,块注释在Go中最常用于包注释。
- 下面从包注释、结构体(接口)注释、函数(方法)注释、代码逻辑注释以及注释规范方面进行说明。
包注释
每个包都应该有一个包注释来介绍这个包。包注释应该包括包的简介,概述这个包用于做什么。
特别是在大型包中,包注释可以提供API最重要部分的简要概述,并根据需要链接到其他文档注释。
// Package path 实现了通用的斜杠分隔功能。
// Package path 应该只用于由正斜杠分隔的路径,例如url中的路径。
// 这个包不处理带有驱动器号或反斜杠的Windows路径;要操作操作系统路径,请使用[path/filepath]包。
package path
[path/filepath]中的方括号是一个文档链接。
从这个例子中可以看出,Go文档注释使用完整的句子。对于包注释,这意味着第一句以“Package ”开头。
对于多文件包,包注释应该只在一个源文件中。如果多个文件具有包注释,则将它们连接起来,形成整个包的一个大注释。
结构体注释
简单结构体注释
结构体注释应该解释该类型的每个实例所代表的含义或者提供的内容。如果API很简单,文档注释可以很短。例如:
package zip
// Reader提供 ZIP 压缩文件中的内容。
type Reader struct {
...
}
方法注释
package strconv
// Quote returns a double-quoted Go string literal representing s.
// The returned string uses Go escape sequences (\t, \n, \xFF, \u0100)
// for control characters and non-printable characters as defined by IsPrint.
func Quote(s string) string {
...
}
推荐文章: