プログラムにおいて、コメントはコードリーディングを助ける重要なものですが、その必要性と妥当性について考えてみましょう。
コメントとは
プログラムの動作に影響を与えない、「コードの解説文」です。//や、/**/、あるいは#や<!-- -->など、プログラミング言語によって様々な構文があります。
コメントの重要性
冒頭に挙げたように、コメントの主な目的は、チーム開発において、コードリーディングを円滑にすることです。
チーム開発では、周りが全員ベテランの開発者であるとは限りません。時には、経験の浅い新人がプロジェクトにアサインされることもあります。
ベテラン開発者同士であれば、他人の書いたコードの意味するところはすぐに分かりますし、読みやすくコードを書く術も心得ています。しかし、あまり経験の無い方が書いたコードは、ベテラン開発者さえも解読困難なコードになっていることがあります。
これは悪いことではありません。例えば、初めて英語や中国語などの新たな言語を習得しようとしたときに、ネイティブスピーカーにとって聞き取り困難な発音をしてしまうことによく似ています。ベテラン開発者にとって新人は、他国から来て間もない人とほとんど変わりはありません。
ですから、妙なコードを書く人がいても、決して怒らずに手を差し伸べてあげてください。そうすることによって、その技術者は驚くほどの進化をしてくれるはずです。
コメントは理解を助けるもの
とはいえ、チーム開発には殆どの場合、スケジュールも納期もあります。未熟な技術者の指導に付きっ切りというわけにはいきません。
この場合、適切なコメントを書くことは非常に有意義なことです。ベテラン技術者にとっても、あるいはそうでない技術者にとっても、コメントはコードの理解を早める大きな道標となります。
書くべきコメント
コメントが無いと理解できないコードには、全てコメントを書いてしかるべきでしょう。ただし、コードを書いた人は、そのコードが当然に理解できるわけですから、「何が理解できないコードなのか？」が分からないことも多いはずです。
客観的な視点に立てる人は的確なコメントを書けますが、そういった視点を持っている人はまれです。可能ならコードレビューを受け、アドバイスを得るとよいでしょう。
書くべきではないコメント
まず、目的を明確に持ちましょう。コメントは一体何のために書くのか考えてみることです。
先ほどの言語の例に倣ってみましょう。“Apple”は、英語でりんごを指します。これは、日本人であっても、殆どの人が理解できます。
このように、Appleに「りんご」と注釈を付けなくても理解できるものに、わざわざ注釈を付けることは、逆に読みづらくなってしまう原因となりますよね。
「でも、子供は読めないじゃないか！」と思ってしまうかもしれませんが、プロジェクトにプログラマとしてアサインされる人は、例えば学校や研修などである一定の教育を受けてきた人しかいないはずです。
つまり、「Appleがりんごである」と理解できる人しかプロジェクトにはいないので、自明の事柄についてわざわざコメントをつける必要はないということです。
コメントを書かないために
理解しやすいコードを書きましょう。
適切な名前をつける
たとえば、適切な名前を付けます。変数、フィールド、メソッド、クラスの全てにわかりやすい名前を付けます。
また、メソッドを切り分けることで処理に名前をつけることができます。そしてそれはたいていの場合、コードによい影響を与えるはずです。
public boolean login(String userId, String password){
// 既にログインしているか確認する
if(loggedInMap.containsKey(userId)){
// ...
}
// ...
}
この場合、loggedInMapにuserIdがあるかどうかを調べることが、「ログインしているかどうか」を調べていることと直接結び付くわけではありません。つまり、処理内容を見て処理概要を推測する必要がありますから、もしかすると誤解を生んでしまうかもしれません。
しかし、以下のようにメソッドとして切り分け、名前を付けることで処理の意味がダイレクトに伝わり、コメントを書く必要がなくなります。
public boolean login(String userId, String password){
if(isLoggedIn(userId)){
// ...
}
// ...
}
private boolean isLoggedIn(String userId){
return loggedInMap.containsKey(userId);
}
代わりに、メソッドに処理概要としてJavaDocを書くことはよい考えでしょう。
シンプルな記述を心掛ける
これは非常に難しいことです。プログラミング言語やフレームワークへの正しい経験と理解が必要で、一朝一夕で出来ることではありません。日本語でも、物事を簡潔に文章化ことは非常に難易度の高いことです。
しかし、可能ならこれ以上に心掛けるべきことは無いでしょう。30行かかるコードが10行になれば、コードを理解するための労力も1/3で済むと言うことです。
ただ、シンプルにするということは単純にコードの記述量を減らすということではありません。日本語においても、平仮名をすべて省略して書いたとしても、理解可能な文章は出来上がるでしょうが、非常に読みづらくなってしまうことは想像に難くありません。
プログラミングでも同じことで、例えば三項演算子を多用するなどすれば確かに記述量は減らせますが、それが本当に読みやすいかどうかは別の話です。
このように、「シンプル」という言葉は、些か概念的すぎる問題があります。これを正しく理解し、記述出来るようになるためには多くの努力か、長い年月を必要とするはずです。
このギャップを埋めるためにコメントを使うことは、悪いことではありません。
まとめ
コメントは便利なものですが、過不足なく適切に書くことは、実は結構難易度の高い作業になります。
コメントはあくまで理解しやすくすると言う目的のための手段であることを念頭に置いて、コードの適正化を行いたいものですね。