分かりやすいコメントを付けて分かりやすいプログラムを書こう

2010.05.28

未だに風邪が治らない kimoto です。そろそろ 2 週間くらいになりそう。

さて先日、社内の意識統一のため、基本的な事ながらコメントの勉強会を行いました。
その時に話した内容をまとめてみましたので、アウトプットしてみようと思います。
何かの参考になれば幸いです。

コメントとは誰の為に書くのか？

答え・読む人の為

コメントとは、後から読む人の為に付ける物、という事になります。
この「読む人」には「他人」だけでなく「自分」も含まれます。
他の人がコードを読む際の理解を促す役割、と同時に自分が後から読み返した時の為でもあります。みなさん経験あると思いますが、自分が書いたコードでも、3日も経てばすっかり忘れます。もはや他人の書いたコードです。その時の為にきちんとコメントを書いておきましょう。
自分だけしか関わらないプロジェクトだったとしても、きちんとコメントを付けるのが重要です。
ちなみに僕の場合は3時間で他人のコードになります。

コメントの役割とは？

答え・コードの説明（What と Why）

コメントは、読む人の為の物であり、そのコードを説明する為の物です。役割は大きく二つ。
まずは「What」、これは何なのか、という説明です。主にブロック単位で付ける事が多いですね。このメソッドは、これこれこういう事をしています。このクラスはこんな感じの役割を果たしています、など。
そしてもう一つ「Why」、なぜこのような書き方をしているのか？という補足的役割です。
例えば、「このコード、直接 DB に入れればいいのに、なんで一度 euc に変換してるんだ？」などと言った場合に、「/* 文字化けが発生するため一度 euc_jp に返還してから格納 */」などと書いてあれば、一発で理由を理解できます。

また、内容の説明をする場合は、単純に何をしているのかを説明するのではなく、仕様の説明をするように心がけると良いでしょう。

//  ユーザ ID が NULL なら
if (is_null($user_id)){
    return false;
}

これは直接やってる事を書いているだけで、本質を書いていません。

// 入力値をチェック
if (is_null($user_id)){
    return false;
}

このように書くのがベターです。

コメントを通じて綺麗なコードを書く意識

上で「What」「Why」の説明をしました。そして、もうひとつ、やってしまいがちなのが「How」です。「How」＝「どのように実装しているか」という説明ですが、コードが分かりやすくシンプルに書かれていれば、この「How」は書かなくて済むはずです。「How」のコメントに頼らず、コードがなにをやっているのか自明な状態を目指しましょう。
また、「How」に頼らないために心がけたい事としては、変数名、メソッド名はぱっと見で分かりやすい物を心がけると良いですね。

$id;
$mode;

こういうのは分かりづらい典型例です。せめて

$user_id;
$display_mode;

このように書くのが良いでしょう。

もう 1 点。
一見、美しいコードが書けた！と思ったときでも、実はトリッキーな書き方をしてるだけで、他人からすると分かりづらいコード、と言う事もあったりします。そんな時、コメントで何をしているのか説明したくなりますが、これも結局は「How」の典型的な例になります。
他人に分かりづらい、と分かってるくらいなら、シンプルに書き直すのが吉です。

さいごに

ネットでコメントについての意見を探すと、極力書かないように、という事を推奨している方もたくさんいらっしゃいます。
理由は、コードを読めばわかる、分からないならコードが悪い、仕様変更でコメントのメンテナンスが追いつかない、などなど。
どれも正しい意見だと思いますが、個人的には極力排除、とまではする必要はないと感じています。
バランスは重要ですが、きれいなコードを意識しつつ、後から読む人の為に適度にコメントをつけるのが良いと思います。

結局コメントも、良いコードを書く為の要素の一つです。
人に読まれる事を意識し、良いコードを書くよう、心がける事が大切だと思います。