ハマログ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

メンバーと共有したこと

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

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

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

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

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

勉強会

  sm   2019年12月13日


関連記事

PHPのcurlを卒業して、Guzzleを使う。の巻

PHPでHTTP通信するときに、PHP組み込みのcURL(Client URL …

【新人エンジニア向け】システム開発で覚えておきたい3つの環境について解説!

エンジニアになって4ヶ月が経ちました。 エンジニアになるとよく耳にする言葉が「環…

Laravelのパンくずリスト(Breadcrumb)の実装(リンクとJSON-LD)

Laravelのパンくずリストを実装します(ついでにJSON-LDも出力します)…


← 前の投稿

次の投稿 →