笔记大全

golang 注释规范

更新时间：2023-10-06

Golang注释规范：为了提高代码可读性、可维护性，注释是至关重要的，Go语言在注释规范上确立了很多约定俗成的规则，本文将从以下四个方面详解这些规范： 1. 代码注释的类型 2. 注释的位置 3. 注释的内容和格式 4. 程序包和导出函数的注释规范

1. 代码注释的类型

Go语言中的注释有两种类型：注释和文档注释。注释是指以//开头的单行注释或以/* */包裹的多行注释，仅对代码本身做出解释和说明，不包含包、变量、函数等的文档相应信息。

func main() {
    // 打印Hello, World!
    fmt.Println("Hello, World!")
}

文档注释相较于普通注释更具有作用，是一种自包含的、有规范格式的注释形式，包含了对包、变量、函数等常量的描述和规范化的说明，能够被godoc命令所解析和生成API文档。文档注释以/* */包裹，其中以"// "开头的注释描述在文档中是less important，以"/* "开头的注释描述在文档中是important，以"/* *" 开头的注释描述在文档中是Premier。

/*
Package strconv 实现了基本数据类型与其字符串表示的相互转化。
内部只涉及Unicode的大部分。
*/
package strconv

2. 注释的位置

在注释的位置上，Go语言提供了一些约定俗成的规则： - 单行注释需要单独爆露在需要描述的代码之上。 - 多行注释可以放在待描述代码的旁边或下方。一般而言，可以将多行注释作为函数、常量或文件的最顶上说明主要作用或注意事项，而将单行注释作为代码中的局部描述。为尽可能提高代码的可读性和可维护性，避免被代码覆盖或忽视，建议在每个程序代码块顶部都加上注释。

// 让机器人们前去寻找Terminator...
func findSkynetIndividuals() []Individual {
    // 从最开始的连接节点开始，按层次追寻关联的节点
    for _, connNode := range connections {
        // 找到根节点
        if connNode.isRoot() {
            // 开始追踪其它联系
            individuals := connNode.findIndividuals()
            // 返回对找到的所有个体进行排序后的结果
            return sortIndividuals(individuals)
        }
    }
    // 没有找到关联人才
    return nil
}

3. 注释的内容和格式

文档注释需要遵循一定的格式，Go的文档注释格式类似JavaDoc，通过godoc工具可以自动提取代码注释，并以HTML的形式生成相应的代码API文档。例如，包的注释应该以"Package 名称"开头:

/*
Package strconv 实现了基本数据类型与其字符串表示的相互转化。
内部只涉及Unicode的大部分。
*/
package strconv

函数的注释应该以"func 函数名(函数参数) (返回参数)"开头：

/*
GetName 返回指定ID的用户名称。
如果找不到相应ID的用户，返回 nil。
*/
func GetName(id int) *string {
    // ...
}

常量的注释应该以"常量名称"开头:

// SecondsPerDay 代表一个标准日的秒数。
const SecondsPerDay = 86400

而变量的命名前缀大写字母代表着该变量是导出变量，需要有规范的注释。

4. 程序包和导出函数的注释规范

每个程序包应该有一个文档注释的package级别注释。该注释应该介绍该程序包的基本用途和功能，一些实际应用示例和注意事项等。例如，下面是对sql包的注释：

/*
Package sql 提供了一个通用接口来操作SQL(DMQL、DDL…)
*/

package sql

同时，每个导出函数和变量要有规范的注释格式。更加详细的，对导出函数的注释应该涵盖以下内容： - 函数名称和用途。 - 形参的意义和功能。 - 返回值的类型和意义。 - 函数执行过程中的一些注意事项。

/*
Query 在连接中运行一个查询，并将结果作为Rows结构相邻地返回。
*/
func (c *Conn) Query(query string, args ...interface{}) (*Rows, error) {
    // ...
}

总结

注释作为代码世界里面的“标识牌”，为代码的可维护性和可读性做出了重要的贡献，Go语言为文档注释提供了一系列约定俗成的规范。在代码开发中，我们应该尽可能地遵循这些规范，不仅保证了代码注释的清晰具体、规范明了，还提升了代码“文化品质”，使得协作开发的人员更加有效、高效地理解代码，降低了交流和开发成本。

c语言编程笔录