16-コメントについてのコメント

「プログラマが知るべき97のこと」の16個目のエピソードは、コメントに関する話題です。本文に書かれているように「コードは、次に見る人がすぐに理解できるように書く」事が大切です。その為には可読性の高い美しいコードを書くわけですが、その中でコメントの持つ比重は大きいでしょう。有効なコメントがなければ理解しにくいコードとなりますし、不適切なコメントはコードの理解を阻害します。酷いケースではコメントが間違っていることもありますが、あれほど腹ただしいものもありません。

「書くのに苦労したコードは、読むのにも苦労する」

コメントは他人がコードを読む場合にも重要なのですが、自分のコードを読む場合にも重要です。以前に書いたコードが読みにくいという経験は、誰もがあるのではないでしょうか？しかし、書くのに苦労した複雑なコードでもそのコードを書いた目的や苦労した点がかかれていると大きなヒントになります。

「このコードはどういう目的でかかれたものか」

コメントを書く理由は複雑なコードの説明と考えてしまいますが、それは基本的に誤りです。リファクタリングによれば、「コメントは消臭剤」と呼ばれています。コードは読めばロジックを理解する事は可能です。しかし、そのロジックをどうして適用したのかは書いた人を除いて解らないのです。コメントはどういう目的でそのコードを書いたかを書くべきです。

また、コメントには大きく分けて２つの用途があることも言及されています。１つ目はドキュメンテーションコメントで、APIのドキュメントです。JavaDoc等のツールを用い、そのAPIの実装を詳しく理解する必要なく利用できることが望ましい形です。可能な限りは先にドキュメントを書いてから実装する方が良いでしょう。TDD（テスト駆動開発）でテストを先に書くのは慣れてきましたが、ドキュメント駆動で書くのはまだまだ苦手です。
２つ目はインラインコメントで、コードの理解を助けるためのコメントです。自分は、コメントレスで理解できる事が理想ではないかと思います。その中で必要なインラインコメントとは、コードの目的や実装の経緯などの付随情報です。決して次のようなコメントは書くべきではないでしょう。

// xに10を代入する
int x = 10;
// yにxの二乗を代入する
int y = x * x;

このようなコメントは、コードと同じ事を日本語で記述しただけのコメントで、コードのノイズにしかなりません。どうしてこのような文化になっているかは不明ですが、もしこのようなコメントを推奨する開発環境であれば見直すべきかと思います。
適切なコメントは美しいコードを書くよりも難しいかもしれません。美しいコードには型がありますが、美しいコメントの型はほとんどありません。もっと美しいコメントをサボらずに書けるようになりたいですね。

プログラマが知るべき97のこと