05章『コメントすべきことを知る』

＃コメントの目的とは？

　→書き手の意図を読み手に知らせること

 

＃＃考え方その①（コメントすべきでは「ない」こと）

　　・コードから”すぐに"わかることをコメントに書かない

　　　例えば、//コンストラクタとか

　　・コメントのためのコメントをしない

　　　→コメントを書くことが目的のコメントを書くべきでは、ない。

　　・ひどいコード（例えば、ひどい名前の関数）を補うような補助的なコメントならば、

　　　コメントを書くのでなく、コードを修正する。

 

＃＃考え方その②（自分の考えを記録する）

   ・監督のコメンタリーのようなコメントに対する大切な考えを書く

　　例えば、以下のものがある。

         →//このクラスは汚くなってきている

         →//サブクラス'ResourceNode'を作って整理した方が良いかもしれない

　・コードが進化している過程で欠陥が生まれた場合、コメントつける必要がある。

　　記法を以下に記載

        →TODO: … あとで手をつける

        →FIXME: … 既知の不具合があるコード

        →HACK: … あまり綺麗じゃない解決策

        →XXX: … 危険！大きな問題がある

　　※大切なのは、これからコードをどうしたいか書くこと

　・定数にまつわる背景を書く

　　例えば、以下のようなものがある

　　//合理的な限界値、人間はこんなに読めない

　　const int MAX_RSS_SUBSCRIPTIONS = 1000;

 

＃＃考え方その③（読み手の立場になって考える）

　※読み手…プロジェクトを熟知していない人のこと

　・質問されそうなことを書く

　　→読み手が「えっ？」って思うところを予想してコメントを書くこと

　・ハマりそうな罠を告知する

　　→平均的な読み手が驚くような動作はコメントをしておく

　・「全体像」をコメントする

　　→ファイルやクラスには、全体像のようなコメントを書く

　　　例えば、//このファイルには、ファイルシステムに関する便利なインターフェースを提供

　　　また、関数の内部にも「顧客が自分で購入した商品を検索する」のような要約のコメントを書くと良い

 

＃＃考え方その④（自分の考えていることを書き出す）

　・コメントを書くのは、めんどくさいがとにかく考えてたことを書きだすことが大切

　　また、書き出してから曖昧な表現を修正すると良い。 

 

担当：らうみー