わたしの愛するエンジニアライフ: 「ソースコードの質」と「可読性」について、議論しよう

http://el.jibun.atmarkit.co.jp/jibunlove/2010/12/post-55bd.html

何やら可読性についての特集を見かけたので私も思うところを書いてみます。

可読性上げるためとして良く言われることに、「コメントを書け」というのがあります。

確かに適切なところに適切な内容のコメントを記述することは可読性に大きく寄与するでしょう。

ですが、ただ書けばよいというものではありません。コメントにも良いコメントと悪いコメントがあります。

以下、思いつくままに私が考える良いコメントと悪いコメントの条件を挙げてみます。

良いコメントの条件

コードで読み取れない意図や、実装方式の背景、経緯について書かれている。

これは言うまでも無いでしょう。このような情報があれば、「どのようにして」という観点だけでなく、「何故、どうして」という観点からも理解を深めることができます。

大きな枠組みを理解するのに役立つ情報が記載されている。

プログラムのコードは様々な他のコードと関連しながら構成されています。これらの関連性について説明されていれば、プログラム全体を俯瞰して全体の概要を捉えるのに役立ちます。

複雑で理解が難しいアルゴリズムについて説明している。

分かりやすく書くに越したことはないですが、時には性能上の理由から複雑なアルゴリズムを実装しなければならないこともあります。(コンピューターの性能向上が著しくほとんどそんな機会はありませんけど。)このようなコードについての説明や、アルゴリズムの詳しい説明への外部参照などがあれば理解が進みやすくなるでしょう。

悪いコメントの条件

コードを見ればすぐにわかることが、そのままコメントにも書かれている。

コードから得られる以上の情報を全く提供していないコメントは悪いコメントです。冗長であり、コードを読む側に対して何も情報を提供していないだけでなく、コードの記述が散慢になり、気が散りやすくなります。

コードで行なっている処理とコメントで説明されていることが違う。

このようなコメントはコードの読み手に混乱をもたらします。まさに百害あって一利無しです。

なぜコードとコメントが食い違うのでしょうか。最初はコードとコメントは一致していたはずです。しかし、様々な改変・修正が行われ、コードが変更されたにもかかわらず、コメントが保守されずに放置され、このようなことになることがあります。コードはコンパイルされ、テストされ、正しく動作することを確認されますが、コメントは実際の動作に影響がないからです。

良いコメントと悪いコメントの条件を書きましたが、実のところ、私は個人的には良いコメントも含めてコメントはできるだけ少ないことが好ましいと考えています。

コメントを書くのは（特に質の高いコメントを書くのは）コードを書くのと同様に時間（つまりお金）がかかかります。わかりやすいコメントを書くのと、わかりやすいプログラムを書くのとではどちらがよいでしょうか。

コメントはコンパイルして実際に動かして評価することはできません。常に人がコードに矛盾が無いように保守する必要があります。したがってわかりやすいコードを書くことに時間をかけることのほうが大事であると考えます。プログラムは、うまく書けば、散文のようにして読めるほどわかりやすく書くことも不可能ではありません。（ただし、英語が苦手な人の多い日本では少し厳しいかもしれませんが。）

もちろん、まったくコメントが不要とは思いません。適材適所です。ダメなのは、わかりやすいコードを書く努力を放棄してコメントを書くことに逃げてしまうことです。

これらの考えに反対する人もいるでしょう。答えはひとつではないと思います。私もそのうち意見が変わるかもしれません（笑）。いずれにしても、もっとわかりやすいコードを書くことの大切さを認識し、考える人が一人でも増えることが大事なのではないかと思います。