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

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

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

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

自分の考えを記録する

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

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

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

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

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

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