リーダブルコード:5~6章 優れたコメント

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

上記書籍をまとめと自分の考えを記載します。

 

コメントに書くべきこと。

  • コードからすぐにわかることはコメントに書くべきではない。
  • 優れたコメントよりも優れた名前の方が大切。

コメントに書くべきではないこと。

  • 優れたコメントとは「考えを記録する」ためのもの。
  • 読み手の立場になって質問されそうなことを想像する。
  • コードの欠陥に気がついたらコメントを書く。
    すぐに対応できないのであれば、気付いた時にコメントを残しましょう。

コメントの書き方。

コメントは簡潔に書く。

コメントには画面の領域を取られますし、読むのにも時間がかかるので、簡潔なものでなければなりません。

入出力のケースをコメントに書く。(個人的に非推奨)

コメントに書くのではなく、テストコードで表現すべきだと思います。

ファイルが別になったりして読みにくいかもしれませんが、テストコードの方が安心です。

コードの意図を書く。

プログラマがコードを書くときに考えていた言葉でコメントを書きましょう。

ドメインの言葉で書きましょう。

具体的には下記のような違いになります。

改善前

# productsを降順でソートする。
def sortDesc(products)
#....
end

 改善後

# productsを値段の高い順でソートする。
def sortDesc(products)
#....
end