『リーダブルコード』第5章 コメントすべきことを知る

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

コメントの目的は、書き手の意図を読み手に知らせることである。

コメントするべきではないこと

  • コードからすぐにわかることをコメントに書かない
  • ひどい名前はコメントをつけずに名前を変える

自分の考えを記録する

  • 「監督のコメンタリー」を入れる:コードの意図を説明する
  • コードの欠陥にコメントをつける:TODO, FIXME, HACK, XXXなど
  • 定数にコメントをつける

読み手の立場になって考える

  • 質問されそうなことを想像する
  • ハマりそうな罠を告知する
  • クラスやファイルに「全体像」のコメントをつける
  • ブロックごとに要約コメントをつける

「コードを理解するのに役立つものなら何でもいいから書こう」

ライターズブロックを乗り越える

  1. 頭のなかにあるコメントをとにかく書き出す。
  2. コメントを読んで(どちらかと言えば)改善が必要なものを見つける。
  3. 改善する。

コメントを残す