リーダブルコード:5~6章 優れたコメント
リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)
- 作者: Dustin Boswell,Trevor Foucher,須藤功平,角征典
- 出版社/メーカー: オライリージャパン
- 発売日: 2012/06/23
- メディア: 単行本(ソフトカバー)
- 購入: 68人 クリック: 1,802回
- この商品を含むブログ (104件) を見る
上記書籍をまとめと自分の考えを記載します。
コメントに書くべきこと。
- コードからすぐにわかることはコメントに書くべきではない。
- 優れたコメントよりも優れた名前の方が大切。
コメントに書くべきではないこと。
- 優れたコメントとは「考えを記録する」ためのもの。
- 読み手の立場になって質問されそうなことを想像する。
- コードの欠陥に気がついたらコメントを書く。
すぐに対応できないのであれば、気付いた時にコメントを残しましょう。
コメントの書き方。
コメントは簡潔に書く。
コメントには画面の領域を取られますし、読むのにも時間がかかるので、簡潔なものでなければなりません。
入出力のケースをコメントに書く。(個人的に非推奨)
コメントに書くのではなく、テストコードで表現すべきだと思います。
ファイルが別になったりして読みにくいかもしれませんが、テストコードの方が安心です。
コードの意図を書く。
プログラマがコードを書くときに考えていた言葉でコメントを書きましょう。
ドメインの言葉で書きましょう。
具体的には下記のような違いになります。
改善前
# productsを降順でソートする。
def sortDesc(products)
#....
end
改善後
# productsを値段の高い順でソートする。
def sortDesc(products)
#....
end