ハマログ

株式会社イーツー・インフォの社員ブログ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

メンバーと共有したこと

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

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

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

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

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

勉強会

  sm   2019年12月13日


関連記事

AWSのロードバランサーでリダイレクト設定

リダイレクト設定 一時的にサイトを止めたい、まだ公開前のパスにアクセスさせたくな…

XAMPPのphpMyAdminを最新版にアップグレード

XAMPP for WindowsのphpMyAdminを最新版にアップデートす…

特定の文字列を検索したいときあるじゃん?

コマンド覚えてないんですよね。 ってことで、コマンドラインで作業する際に、「あ、…


← 前の投稿

次の投稿 →