コードにコメントを書くべきですか?
コメントは確かに用途がありますが、ほとんどの場合、プログラマはコメントを濫用しています。コードに混ぜられたコメントには反対です。コメントはコードから独立すべきだと思います。
次のコードを見てください。
/* /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);
});
私は架空のコードで自分の観点を証明していますが、実際のプロジェクトでもコードを改善してコメントを減らすことができると信じています。