勉強会 – コメントについて

開発メンバーで勉強会で学んだ内容を書き記したいと思います。

コードに対する共通認識を持つために「リーダブルコード」を題材にしています。

今回は5章の「コメントすべきことを知る」

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

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

コードを見てすぐにわかることはコメントしない。

//インフォメーションのコントローラをクラス定義
 class InformationController
 {
     //一覧という文字列を出力する関数、echoIndexを定義
     function echoIndex()
     {
         //文字列、一覧を出力
         echo '一覧';
     }
 }

・上記のような、コードを見て「すぐ」わかるようなコメントは、新しい情報を提供するわけでも、理解しやすくなるわけでもないので、全く価値がない。

【自分の考えを記録】
// 定数にコメントをつける
定数は、何をするのか・なぜその値をもっているかという「背景」をもっている場合が多い。

// これ以上大きいとレイアウトが崩れる
MAX_PRODUCT_NAME = 20;

コードが未完成のときは、以下のように書いておく
// TODO: もっと高速に処理する

【読み手の立場になって考える】
ハマりそうな箇所を予め予測し、告知する

自分に問いかけながら、あらかじめ問題を予測してコメントできるとよい。

〇メンバーと共有したこと

（一度に共通認識として実行は難しいので、絞りました。）

コメントすべきでないこと
・コードからすぐに読み取れることはコメントしない

記録すべき自分の考え
・伝わりにくい定数にはコメントつける
・コードの結果をTODO: などで記法を使って示す。

読み手の立場になって考える
・コードを読んだ人が「え？」と思うところを予想してコメントをつける

コメントのバランス、難しい。。