关于变量和常量的注释应描述其内容而非其目的
发布者:admin 发表于:417天前 阅读数:690 评论:0

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

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)

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