ハマログ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

メンバーと共有したこと

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

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

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

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

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

勉強会

sm   sm   2019年12月13日


関連記事

Laravel4.2のソフトデリート(論理削除)について

Laravel4.1で開発中のシステムをLaravel4.2にアップグレードしま…

爆速PHPフレームワーク「Phalcon」をお試し

浅春の候、皆様におかれましては益々ご健勝のこととお慶び申し上げます。 Shinが…

Macで.DS_Storeファイルを作成しない方法

こんにちは、かねこです。 Mac OSで、Finderでリモートサーバ接続すると…


← 前の投稿

次の投稿 →