コードにコメントを書くべきですか?


多くの先輩が後輩に注釈を多く書くように教育している時、ネット上にはプログラマーがコメントを書かない段差が溢れています。タイトル党として、まず私の観点を修正してください。コードが十分によく書けば、大多数の注釈は余分です。より良いコードを書くことによって、より多くの注釈を代替するべきです。
コメントは確かに用途がありますが、ほとんどの場合、プログラマはコメントを濫用しています。コードに混ぜられたコメントには反対です。コメントはコードから独立すべきだと思います。
次のコードを見てください。

/* /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;
}

あなたは意外にも半分の時間を使って注釈の上で読んで、これはなんと生命の事を浪費するので、コードの中で1行の注釈をプラスしますと、いずれもコードの読むコストを増加します――たとえ読者はすでに注釈の伝達する精神を理解しましたとしても;このコードを修正した人は注釈と一緒に修正しなければなりません。そして彼が果たしてそうするかどうかは確認できません。
したがって、非常に必要な場合にのみ、コメントを追加する必要があります。注釈はコードの一部が何をしているかを説明してはいけません。これは各資格のプログラマが知っているべきことです。このコードはなぜこのようにしますか?
これにより、いくつかの明確に追加すべきでない注釈が導き出される。
本システムによって記録されるべき情報、コードに対するコメント、および重要でないTODO。
コードは全部ではなく、一点によるプロジェクトには、自分のバージョンコントロールシステムがあります。コードの違いを記録する以外に、リストとIssueの機能があるべきです。
コードを読む人は通常、いくつかのプログラマーの間の恩讐を知る必要がなく、多くの時もこのコードの歴史を気にしないで、これらの情報はコードをどんどん長くするだけです。
廃棄コード
破棄されたコードは削除されるべきです。これらのコードは読書に非常に影響します。
ほとんどの場合、使われていないコードは再利用されません。少数の場合でも、バージョン制御システムからそれらを見つけることができます。
変数と関数名の解釈
この場合、より適切な名前が必要であることは明らかです。この識別子には比較的小さな役割がある場合、より長い名前を使って、より多くの情報を格納することができます。
例えば、上記のように:
productsはproductsに変更するべきです。id。
sumはtotal_に変更すべきであるグループ
dataはプロジェクトに変えるべきだ。レコード
文法に対する解釈及び分かりやすいこと
例えば上記の「商品の価格を総金額に加算すると、a+=bはa=a+bの略語」です。これは誰でも知っていることです。
このような注釈を書くことによって、考えを整理する人がいるかもしれません。

// :
//    ID
//    ID
// :
//   
//   
でも、コードが書き終わったら削除してください。
論理ブロックの要約
例えば、上記の「各パラメータをフィルタリングする」と「商品ごとの総金額を計算する」という場合は、あなたが論理的に抽象的ではなく、具体的な表現は以下のようになります。

// 25 A
// 5 B
// 90 C
// 45 D
この結果、いくつかの注釈が必要となり、この4つの部分を分割します。この4つの部分が全部関数で呼び出された場合、関数名自体は論理の解釈であり、読者は最初の25行で用事Bの5行のコードを検索する必要がなく、関数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);
});

私は架空のコードで自分の観点を証明していますが、実際のプロジェクトでもコードを改善してコメントを減らすことができると信じています。