关于变量和常量的注释应描述其内容而非其目的

我之前谈过，变量或常量的名称应描述其目的。 向变量或常量添加注释时，该注释应描述变量内容，而不是变量目的。

const randomNumber = 6 // determined from an unbiased die

在此示例中，注释描述了为什么 randomNumber 被赋值为6，以及6来自哪里。 注释没有描述 randomNumber 的使用位置。 还有更多的栗子：

const (
    StatusContinue           = 100 // RFC 7231, 6.2.1
    StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2
    StatusProcessing         = 102 // RFC 2518, 10.1

    StatusOK                 = 200 // RFC 7231, 6.3.1

在HTTP的上下文中，数字 100 被称为 StatusContinue，如 RFC 7231 第 6.2.1 节中所定义。

贴士:
对于没有初始值的变量，注释应描述谁负责初始化此变量。

// sizeCalculationDisabled indicates whether it is safe
// to calculate Types' widths and alignments. See dowidth.
var sizeCalculationDisabled bool

这里的注释让读者知道 dowidth 函数负责维护 sizeCalculationDisabled 的状态。

隐藏在众目睽睽下
这个提示来自Kate Gregory[3]。有时你会发现一个更好的变量名称隐藏在注释中。

// registry of SQL drivers
var registry = make(map[string]*sql.Driver)

注释是由作者添加的，因为 registry 没有充分解释其目的 - 它是一个注册表，但注册的是什么？

通过将变量重命名为 sqlDrivers，现在可以清楚地知道此变量的目的是保存SQL驱动程序。

var sqlDrivers = make(map[string]*sql.Driver)

之前的注释就是多余的，可以删除。