コメントを美しく書いてみよう！

はじめに

美しいコードを見ると感動する。優れたコードは見た瞬間に何をしているのかが伝わってくる。

でお馴染みのリーダブルコードという本の内容から、コメントに焦点を当てて記載しました。
参考文献：リーダブルコード

これまでの経験と本の内容を合わせて、それっぽいコードをサンプルに記載してまとめています。

コメントを美しく書く理由

リーダブルコードによると

コードは理解し易くなければならない。他の人が最短時間で理解できるように書く必要がある

と記載されています。
つまり、読みやすいコードを書くのが大事です。
そして、一番簡単に誰でも実践できるのがコメントだと思います！

ただし不要なコメントはすべきでない

コメントを多く書けばいいわけではなく、不要なコメントは書くべきではありません。
コメントを読むことで、コードを読む時間が減りますが、その分画面を占領してしまうからです。
そのため、コメントには価値をもたせる必要があり、価値のないコメントはする必要はないとのことです。

例えば

// URLをエスケープする
$url = htmlspecialchars($hoge, ENT_QUOTES);

特に新しい情報はないため、個人的に不要にみえます。
普段こういったコメントは読み飛ばしてる方も多いと思います。

// A123456 のデータから頭文字「A」を除去して6桁の数字にする
$str = substr($hoge, 1);

こちらのコメントも、最初の文字消してるだけで、関数の意味を知ってたら新しい情報はないやん！
って思う方もいると思いますが、コメントを読んだ方が、やってることの理解が早くできるため、書いたほうが良いとされる例です。

// 文字列を分割して登録
$str = explode('-', $data);

// 日付-曜日-時間 を分割して登録
$str = explode('-', $data);

こちらは日時のデータを分割して取得する例ですが
一個目より二個目のほうがどんなデータが入ってくるのかコメントを見れば理解でき結果的にコードの意味が早く理解できます。

コメントに自分の考えを記録しておく

コメントにはコードに対する思いを書いても良い

// 似たような処理があるので、共通関数に移した方が良い

// サブクラスを使って整理したほうが速度が速くなるかもしれない

// 今のデータ内容なら問題ないけど、；がはいったデータが来た場合やばいかも

こういったコメントがあれば、作成者はコードに改善余地があることを認めており
いずれ修正対象になるかもしれません。
コメントがないと誰も修正しなさそうだし、なんか意図があってこういうコードにしたのかなって思う可能性もあります。
大切なことは、自由にコメントを記載して、コードの品質の状態や改善の余地を示したりしておくことです！

読み手の立場になって考える

質問されそうなことを想像して書く
「これってどういう意味だろう？」と思うところにコメントを書くと良いとされています。

// メモリオーバーになる場合があるため、メモリを解放する
unset($data);

コメントがないとunsetしてるのは、単純に変数を消してるだけって思われるかもしれません。
コメントを書いておくことで、メモリ対策であることが分かります。

全体像のコメントを書く
新しく入った人は何やってるか基本的にわからない場合が多いです。
処理の要約を書くことで詳細を調べなくても、だいたいやってることが理解できます。

// 郵便番号から住所を取得する関数
$getAddressData = function(zipcode){

処理の中身を確認しなくても、コメントによってgetAddressDataが何の処理なのかだいたいわかるため
改修箇所と関係があるかないかを、コメントだけで判断できそうです。

コメントは正確かつ簡潔にかく

無駄な行数は使わないで簡潔にかく

// 郵便番号で検索をする
// 戻り値として住所を返却する

この例ですと、内容や文言の量から考えても、まとめて一行に書いたほうが良いように思われます。

あいまいな代名詞は避ける

// 郵便番号から住所を所得するので、そのデータを検証する

そのデータを検証するの「その」が指してるのが
「郵便番号」なのか「住所」なのかそれとも両方なのかが、はっきりとは分かりません。
「その」や「これ」とか曖昧な代名詞は避ける方がわかりやすくなります。

まとめ

・コメントには価値をもたせよう。価値なきコメントは削除しよう
・コメントにコードに対する思いを書こう
・読み手の立場になってコメントをどう書くか考えよう
・コメントは正確かつ簡潔にかこう