リーダブルコードの要約_5章 #リーダブルコード

5章コメントすべきことを知る
コメントの目的は、「書き手の意図を読み手に知らせること」である。
本章ではコメントについて以下の３つのポイントを解説する。

コメントすべきでは「ない」ことを知る

【コードからすぐにわかることをコメントに書かない】

class Account {
    //コンストラクタ
    function __construct() {
        ...
    }
...
}

このコンストラクタというコメントは、コードからわかること以上の新しい情報を読み手に提供しておらず、価値のないコメントである。こういうコメントは残すべきではない。

コードを書いているときの自分の考えを記録する
優れたコメントとは、書き手がコードを書いているときに持っている「大切な考え」を記録したものだ。
【コードの欠陥にコメントをつける】
例えばコードに欠陥があるときは、それを文章化しておくと良い。

    // TODO: もっと早いアルゴリズムを使う

こうしたコメントを残すことで、コードの品質や状態を知らせたり、改善の方向を示すことができる。
プログラマがよく使うコメント記法がいくつかある。

※こうした記法をいつどのように使うかについては、チームの規約があるかもしれないので、確認してみるのが良い。

読み手の立場になって考える
【要約コメントを残す】
処理の最初に要約コメントを残すことで、読み手が処理の「全体像」を把握しやすくなる。

foreach ($users as $key => $user) {
   //ユーザがゴールド会員ならクーポンを付与する
   if(...) {
        ...
   }
}

また、関数の中で複数の処理が走っている場合は、処理ごとに要約コメントを書いておくと読みやすくなる。

function GenerateUserReport() {
   // ユーザのロックを獲得する
   ...
   // ユーザの情報をDBから読み込む
   ...
   // 情報をファイルへ書き出す
   ...
   // このユーザのロックを解放する
   ...
 }