论代码中为何不该当写注释

当不少前辈教育后辈应当多写注释的时候，当网络上充满了有关程序员从不写注释的段子的时候，这是一个很是有争议的话题。做为一个标题党，容我先修正一下个人观点：我认为若是代码写得足够好，那么大多数注释是多余的，咱们应该经过写出更好的代码来代替更多注释。

注释的确有其用途，但大部分状况下，程序员在滥用注释。我是反对夹杂在代码间的注释的，我认为注释应当从代码中独立出来——一般被称为文档。

请看下面一段代码。

/* /static/market/checkout.js

2014.7.2 create by orzfly
2014.7.29 update by jysperm: fixbugs

TODO: 这段代码中注释太多了，须要移除一些 -- jysperm
*/

var raw_products = req.query['products'].split(',');

// 商品 ID 的数组
var products = []

// 过滤每一个参数
for(var i = 0, i < raw_products.length, i++) {
    if (!raw_products[i]) 
        return;

    // 前端传来的数据中竟然会有空格
    if (!raw_products[i].trim())
        return

    /* 2014.7.22: 如今可使用非数字 ID 了
    // 略过非数字条目
    if (isNan(raw_products[i].trim().toFixed()))
        return;
    */

    products.push(raw_products[i].trim().toFixed());
}

// 总钱数
var sum = 0;

// 计算每一个商品的总钱数
for(var i = 0, i < products.length, i++) {
    // 从数据库中查商品信息
    var data = db.product.byID(products[i]);

    // TODO: 谁来写一下没查到商品的状况

    // 把商品的价格加到总钱数上， a += b 是 a = a + b 的缩写
    sum += data.price;
}

你竟然花了一半的时间在读注释上面，这是多么浪费生命的事情，在代码中每加一行注释，都会增长代码的阅读成本——即便阅读者已经了解了注释所要传达的精神；同时也会增长维护成本：修改这段代码的人不得不连同注释一块儿修改——并且你不能肯定他到底会不会这么作。

因此只有当很是必要的状况下，才应该添加注释，并且应当言简意赅。注释不该当解释一段代码在作什么，由于这是每一个合格的程序员都应该知道的事情，而是应该解释这段代码为何要这样作。

由此引出几种明显不该该添加的注释：

• 本应由版本控制系统记录的信息、对代码的评论，以及不是很重要的 TODO.

  代码并非所有，一个但凡靠谱一点的项目，都应当有本身的版本控制系统，除了记录代码差别以外，还应该有工单和 Issue 的功能。
  阅读代码的人一般不须要了解几个程序员之间的恩怨，不少时候也不关心这段代码的历史，这些信息只会把代码拖得愈来愈长。

• 废弃的代码

  被弃用的代码应该被删掉，这些代码会很是影响阅读，并且它们通常又很长。
  在绝大多数状况下，被弃用的代码不会从新派上用场，即便出现了少数状况，你也能够从版本控制系统中找到它们。

• 对变量和函数名的解释

  这种状况下显然你须要一个更恰当的名字，若是这个标识符有一个比较小的做用于，你可使用一个比较长的名字以便容纳更多信息。

  例如上文中的：

  • products 应改成 products_id
  • sum 应改成 total_amount
  • data 应改成 product_record

• 对语法的解释，以及显而易见的事情

  例如上文中的「把商品的价格加到总钱数上， a += b 是 a = a + b 的缩写」，这显然是任何一我的都知道的事情。

  也许有人愿意经过写这样的注释来梳理思路：

  // 过滤参数：
  //    去掉 ID 里的空格
  //    去掉非数字 ID
  // 循环每个商品：
  //    去数据库查记录
  //    把商品的价格加到总钱数上

  可是当代码写完的时候记得删掉。

• 对逻辑块的归纳

  例如上文中的「过滤每一个参数」和「计算每一个商品的总钱数」，这状况下一般是你没有对逻辑进行抽象，具体表现就是像下面这样：

  // 首先有 25 行代码去作事情 A
  // 而后有 5 行代码去作事情 B
  // 这里有 90 行代码去作事情 C
  // 最后有 45 行代码去作事情 D

  这致使你须要一些注释来分割这四个部分。若是这四个部分都是一个函数调用的话，那么函数名自己就是对逻辑的一种解释，读者能够快速地找到函数 B, 而没必要在前 25 行中搜索作事情 B 的五行代码。

综上，我对这段代码的改善意见以下：

var filterProductID = function(raw_products_id) {
    result = []

    raw_products_id.forEach(function(product_id) {
        if (product_id and product_id.trim()) 
            products_id.push(product_id.trim().toFixed());
    });

    return result;
};

var getPriceOfProduct = function(id) {
    var product_record = db.product.byID(products[i]);

    if (product_record)
        return product_record.price;
    else
        return 0;
};

var products_id = filterProductID(req.query['products'].split(','));
var tatol_amount = 0;

products_id.forEach(function(product_id) {
    tatol_amount += getPriceOfProduct(product_id);
});

虽然我在以一段虚构的，刻意编造的代码来佐证个人观点，但我相信在实际的项目中，一样能够经过改善代码来减小注释，并且整体上来说会节约更多的时间和精力。

http://jysperm.me/technology/1750