どんなに美しいコードであろうが、コメントは書け

「コメントが不要になるぐらい、美しいコードを書け」と良く言います。コードを美しく保つことができれば、あえてコメントによってコードと同じことを説明しなくて良いということですね。大いに賛同するところでございます。コードを美しく保つことは、プログラマーの義務です。

でもコメントは書け。

複数の「日本人」で取り組む、何百万行というコード量のプロジェクトでは、どんなに美しいコードであろうが、コメントは必要だと思うのです。何故って、私のように英語に弱い日本人は、どんなにコードが美しかろうと、コードを理解するのに時間がかかるためです。

リーダブルコードに、以下のような言葉があります。

コードは他の人が最短時間で理解出来るように書かなければいけない

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

まあ、「コードから容易に読み取れることをコメントに書くな」とも書かれているのですが、それは英語圏の話じゃないの？と時折思うのです。命名に日本語を使用するようなプロジェクトは別にして、通常英語のみのコードを読むより、日本語のコメントであたりを付けた方が、解読のスピードは上がるはずです。

例えば、以下のマクロの例です。

#define CUBE (x) ((x) * (x) * (x))

どんなに良い名前が付いていようと、単純なマクロであろうと、それが立方体の体積を求めるマクロだと理解するためには、少しだけ頭を使わなければなりません。コードの解析では、この「少しだけ頭を使う」の連続です。これが積み重なると、大きなコストになるわけです。

対して、冗長とも思われそうなコメントを付加してみます。

// 立方体の体積を求めるマクロ
#define CUBE (x) ((x) * (x) * (x))

うーん、無駄なコメントです。冗長です。

でも書け

行数は２倍です。DRY原則にも反しています。

でも書け

だって、単純に最短時間で理解できるではありませんか。コードを上からスクロールして眺めながら目的のルーチン等を見つけ出そうと思うと、英語の羅列より、時折シンタックスハイライトされた日本語のコメントが現れた方が快適なのです。英語圏の人間であれば、コードと同じことをコメントで説明すると、冗長になることでしょう。しかし、我々は日本人です。

プロジェクトのメンバー、後々に保守するエンジニアは、あなたより英語に弱い可能性があります。あなたが１秒で解読できるコードも、他人は３秒かかるかもしれません。まあ、コメントを書くのにも数秒かかるわけですが。それでも、コメントを書いてほしいのです。

じゃあ、どこまでコメントを書くのか、どういうものが高品質なコメントなのか、という話をしだすと長くなるので、それはまたの機会にします。

こんなコメントならいらないというのも、言わずもがなです。

c = a + b;    // aとbの和をcに代入する。

何故世の中には、鬼の首を取ったかのように、死ぬほど極端な例を挙げて「冗長なコメントは悪だー」と叫ぶ人が、こんなにも多いのでしょう。それより、有用なコメントのライン引きについて、もう少し議論して頂きたいです。

それから、コメントに嘘を書く奴と、コードを改修する時にコメントも一緒に保守しない奴は、今すぐプロバイダーに解約の電話を入れて、コードをあなた以外の人間に提供しないでください。

ではでは。