情報を付加しないコメントに注意する

プログラミングにおいては日本語でプログラムを書くこと、つまりクラス名、メソッド名、変数名を日本語にしてプログラミングすることはまれだと思います。しかし、コメントを日本語で書くことは普通に行われています。そうすると、次のようなコードを目にすることになります。

// モデル情報を取得する
Model m = config.getModelInfo()

これはコードを読めば分かることを説明しているコメントに過ぎないのですが、日本語で書いてあるので何らかの情報を付加しているような印象を与えます。これを英語で書いたとしたら次のようになるでしょう。

// Gets the model info
Model m = config.getModelInfo()

明らかに「同じこと」を二回書いていることになります。したがって、そもそもこのようなコメントは書かないわけです。

コメントはコードから読み取れない、あるいは分かりにくいことを説明するために書くわけです。しかし、日本語で書くことにより次のようなコメントを目にすることがあります。

• 上記のようにメソッド名が表す意味をそのまま日本語で書いている
• メソッド名が不適切に命名されて処理内容が読み取れないので、日本語のコメントで説明している
• メソッド名が不適な命名で処理内容が読み取れないけれど、そのメソッド名がそのまま日本語に訳されてコメントとして書かれている

コードを読みやすく理解しやすいように書き、その上で読み手に付加情報を与えるためにコメントを書くのです。付加情報のない無意味なコメントが書かれていないか、メソッド名などを適切に変更すればコメントが不要になるのではないかという視点でコードをレビューする必要があります。