浅谈程序注释

入职三个月，国庆回来开始看公司底层框架，Yeah~,老大要带我起(入)飞(坑)了.
老大的代码很是高端，函数一层又一层的，对新东西还是需要花点时间来学习的.
突然就回想起刚入职的时候，看和我合作的客户端同事太忙，准备帮一下，可是我一打开他的代码，我这想法就被我收回了。于是在某脉匿名区发了一贴，大概说”你们遇到没有注释，而且函数名变量名也表达不清的代码怎么办”.结果评论画风大概是”你太年轻了”,”程序本身应具有自我描述性,你代码写得少”之类。也有吐槽自己代码不注释三个月回头不认识的。

规范必然重要，但注释的角色的重要性也不容小觑。

为什么需要注释

正如上面所说，自己写的代码，三个月，回头看自己的代码，不认识。
你说你记性很好，看一眼函数名就能想起曾经为什么要写它，它的功能是啥。那别人来看的时候呢？
你说你代码很规范，函数名变量名取得很简单粗暴易懂。我想这对于你同事(熟悉你项目的人)来说，应该不会有什么困难，但来了一个新人，对项目不熟悉，对函数调来调去搞得晕头转向的，鬼知道你干嘛要这样写啊(有点牵强了)。

我觉得最重要的一点也就是上面最后一点，写代码不仅仅是为了将来自己能看懂，更重要的是新人(不熟悉项目的人)能够花费更少的时间了解到代码意图。

什么是好的注释

  • 英文注释
    这虽然会有一定程度上的阅读影响，但为了防止编码的问题，英语太差也不打紧，英文总比乱码好，想起，刚入职接手第一个小游戏的时候，常定义文件的注释，就被我用vim搞乱码了，回不去了。。。

  • 细节注释
    这对于只是熟悉项目的人来不是非常有必要，但对于需要维护更新的来说，是非常重要的，可能哪天在某个小功能(函数)出了个逻辑错误，维护人员或者写码的人怎么也想不起这里为什么要循环x次，那里为什么要除2，还有那里为什么要包装一下等等，这时候就头疼了。所以在关键或者逻辑复杂的地方注释一下，也是很有必要的。同时，这样写的代码会有什么需要在其他地方控制的也请写出来，比如调用某个函数之前需要在调用之前先初始化哪里变量什么的。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    void shrink(int n) {    // shrink graph
        for(int i = 0; i < n; ++i) {
            for(int j = 0; j < edges[i].size(); ++j) {
                edges[i][j] = cycle[edges[i][j]];   //Careful, this will create self-loop
            }
        }
        for(int i = 0; i < n; ++i) {
            if(cycle[i] == i) continue;
            int u = cycle[i];
            for(int j = 0; j < edges[i].size(); ++j) {
                edges[u].push_back(edges[i][j]);
            }
            edges[i].clear();
        }
        for(int i = 0; i < n; ++i) {//Remove the duplicate edges, Not always necessary
            std::sort(edges[i].begin(), edges[i].end());
            std::unique(edges[i].begin(), edges[i].end());
        }
    }

    这是我强连通模板的缩图部分，我在两个细节地方写了注释，一个是那里会造成自环，如果不要自环，需要控制一下，一个是去掉重边，并不是每个强连通都需要，视情况而定。我想这是相当不错的，

    当然你也不应该在很简单的小细节旁边写上注释

  • 去掉多余注释
    记得好像在哪里看见过说注释占有比在多少之间比较合适，我忘了，但我想这没有固定说法，在认为该注释的地方注释，不该注释的地方，就不要注释了。

    1
    2
    3
    4
    5
    6
    7
    if (query() >= 300) {
    // if products exceed 300, update
        update();
    } else {
    // less than 300, add one
        add();
    }

    比如这样的注释，else那里是没必要的了。

留言

2016-10-10
▲