《编写可读代码的艺术》第5章 该写什么样的注释

1. 什么样的注释是不需要的

    下面的例子中的全部注释没有提供任何新的信息，所以没有价值。

    不要为能从代码中快速推断的事实写注释。

// The class definition for Account
class Account {
    public:
    // Constructor
    Account();
    
    // Set the profit member to a new value
    void SetProfit(double profit);
    
    // Return the profit from this Account
    double GetProfit();
};

2. 不要为了注释而注释

    没有价值的注释：

// Find the Node in the given subtree, with the given name, using the given depth.
Node* FindNodeInSubtree(Node* subtree, string name, int depth);

    如果想要在这注释，最好能给出更多重要的细节：

// Find a Node with the given 'name' or return NULL.
// If depth <= 0, only 'subtree' is inspected.
// If depth == N, only 'subtree' and N levels below are inspected.
Node* FindNodeInSubtree(Node* subtree, string name, int depth);

3. 应当使用好的变量名，而不是给不好的名字加注释

DeleteRegistry听上去是一个危险的名字，注释是为了澄清困惑

// Releases the handle for this key. This doesn't modify the actual registry.
void DeleteRegistry(RegistryKey* key);

    倒不如直接使用一个能自我说明的名字

void ReleaseRegistryHandle(RegistryKey* key);

4. 记录你的思想

    （1）加入“导演评论”

// 出乎意料的是，对于这些数据，用二叉树比用哈希表快40%
// 哈希运算比左右比较大得多

        上面的注释会说明一条很重要的经验，让读者不要为了无谓的优化浪费时间

// 作为整体可能会丢掉几个词，但这不是什么问题。要100%解决太难了

        上面的注释说明了一个小问题不是bug，不用过多浪费时间修复。

// 这个类正变得越来越乱
// 也许我们应该建立一个子类ResourceNode来整理

        上面的注释鼓励下一个人改正它，并给出了具体建议。

    （2）为代码中的瑕疵写注释

标记           通常的含义
TODO:         有待处理的事情
FIXME:        已知的无法运行的代码
HACK:         对某个问题的粗糙的解决方案
XXX:          危险！这里有问题

            具体应遵循团队的规范
    （3）给常量加注释

        下面的注释告诉读者：常量值设置成1就太低了，50可能就太夸张了

const int NUM_THREADS = 8 // as long as it's >= 2 * num_processors, that's good enough.

        可能常量的名字已经够清楚，然而很多常量可以通过加注释进行改进，只需记录下当时的想法而已。

image_quality = 0.72; // users thought 0.72 gave the best size/quality tradeoff

5. 站在读者的角度

    （1）意料之中的提问

        读者可能会问为什么不用data.clear()，可以在注释中回答此问题

struct Recorder {
    vector<float> data;
    //...
    void Clear() {// Force vector to relinquish its memory (look up "STL swap trick")
        vector<float>().swap(data);
    }
};

      （2）公布可能的陷阱

        这个函数可能会花一分钟时间。如果没有注释，可能有人在不知情的情况下错误地调用这个函数，导致邮件服务器宕机时，程序被挂起

// 调用外部服务器来发送邮件。（1分钟后超时）
void SendEmail(string to, string subject, string body);

    （3）“全局观”注释

        对于新成员来讲，最难的事情之一就是理解全局观。几句精心选择的话，比什么都没有强多了。

// 这个文件包含一些辅助函数，为我们的文件系统提供了更便利的接口
// 它处理了文件权限及其他基本的细节

    （4）总结性注释

        下面的注释很好地总结了低层代码

# Find all the items that customers purchased for themselves.
for customer_id in all_customers:
    for sale in all_sales[customer_id].sales:
        if sale.recipient == customer_id:
            #...

        总结性注释使得读者可以在深入了解细节之前就能得到其主旨

5. 克服“作者心理阻滞”

    很多程序员不喜欢写注释，因为要写出好的注释感觉好像要花很多功夫。通过一下方式可以克服这种心理：
    （1）最好的办法就是现在就开始写，把心里想的写下来就好了，可能措辞会有些含糊，但是起码比没有强。
    （2）读一下这段注释，看看也没有什么可以改进的地方。
    （3）不断改进。