GO语言 注释

在编写代码时，注释是对代码的解释和说明，描述变量和函数如何使用以及其他可能有用的信息。 在 Go 中，注释有三种类型：单行注释，多行注释和文档注释。

单行注释

单行注释以 // 开始，直到行末为止，用于解释代码的某一部分。单行注释应使用在变量、函数或语句上方，而不应使用在代码行末。

// 这是一个单行注释
total := num1 + num2 // 这是一个单行注释,位于语句末尾

多行注释

多行注释以 /* 开始，以 */ 结束，可在一行或多行中记录用于解释多行代码的详细信息。

/*
这是一个多行注释，
可以跨越多行
*/

文档注释

文档注释是一种特殊的注释，它用来为 Go 代码提供说明文档。文档注释以 /** 开始，以 */ 结束，其间包含注释文本和针对代码的描述。在使用 go doc 命令查看包时，将显示所有文档注释。

在编写文档注释时，请遵循以下规则：

• 文档注释应在声明方式的上方。
• 文档注释的第一行应简要概述该项的功能。
• 如果注释文本跨越了多行，请确保在每个新行前添加 // 注释。
• 在描述参数、返回值等时，必须详细说明其类型和含义。
• 对于非公共（小写字母开头）的包、类型、变量或函数，只需要简要说明即可。
• 对于公共（大写字母开头）的包、类型、变量或函数，应该写详细的文档注释。

// Package math provides basic mathematical functions.
package math

// Sum adds two integers and returns the result.
func Sum(a, b int) int {
    // Function body ...
}

在上面的例子中，package 语句下面的注释是针对整个包的，解释了该包提供的功能。在 Sum 函数的上方，文档注释描述了函数的功能以及其参数和返回值的类型。

在代码注释的使用上，GO语言比其他很多语言更规范，文档注释更是一大优势。我们在开发中应该加强文档注释的应用，以达到更加高效的协同开发和文档交接。