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

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

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

    1. const randomNumber = 6 // determined from an unbiased die

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

    1. const (
    2. StatusContinue = 100 // RFC 7231, 6.2.1
    3. StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2
    4. StatusProcessing = 102 // RFC 2518, 10.1
    5. StatusOK = 200 // RFC 7231, 6.3.1

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

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

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

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

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

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

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

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

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

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