注释 属于

关于 注释

注释让你能在代码里留下说明，而不影响代码的运行。 单行注释以//开头，//可以出现在行内的任意位置。 编译器会忽略从//到该行末尾的所有内容。 当注释跟在同一行的代码后面时，通常称为行内注释。 多行注释以/*开头，以*/结尾，两者都可以出现在行内的任意位置。 编译器会忽略两者之间的所有内容，可以跨一行或多行。

// This is a single-line comment on its own line

x := 1 // This is an single-line comment inline with code
fmt.Println(x) // prints 1

/*
This is a valid
multiline comment.
*/

/* This is also a valid multi-line comment. */

注释出现在不同位置时，作用也不同。

代码注释

代码注释解释的是为什么要这样做，而不是做了什么。 当某个决定背后的原因无法从代码中一眼看出时，就该用它们：

results = results[1:] // skipping the header row

大多数情况下，写得清楚的代码本身就说明了一切，不需要注释。 偶尔，代码确实需要做一些复杂或出人意料的事情；这类代码就应该加上注释。

文档注释

文档注释用于为包、变量或函数编写文档。 这些文档面向其他想了解如何_使用_你的代码的开发者。 它应该从较高的层面说明代码做什么，以及如何使用。 不应涉及代码内部具体如何实现的细节。 文档注释紧挨在声明之前，注释与声明之间不能有空行。 godoc会解析它们来生成包的文档，就像你在 pkg.go.dev 上看到的那样。 文档注释应该是一个完整的句子，以标识符的名字开头，以句号结尾。

导出的标识符（以大写字母开头的那些）上的文档注释会出现在生成的文档中。 未导出的标识符（不以大写字母开头的那些）上的文档注释不会出现，但它们仍能在代码内部提供有用的背景信息。

为包编写文档的注释以包名开头，并描述这个包的作用：

// Package kelvin provides tools to convert temperatures to and from Kelvin.
package kelvin

为函数编写文档的注释以函数名开头，描述函数的作用，包括它的实参和返回值：

// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
    return 0
}

为变量编写文档的注释以变量名开头，描述这个变量代表什么：

// TemperatureFahrenheit represents a certain temperature in degrees Fahrenheit.
var TemperatureFahrenheit float64

完整的文档注释规范，请参阅 Go 文档指南。