私がソースコードにほとんどコメントを書かない理由

注意: この記事は1年以上前に掲載されたものです。情報が古い場合がありますのでお気を付け下さい。

私はソースコードにほとんどコメントは書いていない。それは、単純に面倒臭いからというわけでも、書き忘れているからというわけでもない。必要以上にコメントを書くことがむしろ有害であるということと、そもそもコメントを書かなくてもちゃんと理解できるようなコードづくりをすべきであり、ちゃんとわかりやすいコードであればコメントがなくても十分に理解しやすいものである。以下、自分なりの意見を書いてみたい。

まず、コメントは、その処理やなぜこうする必要があるのか、処理の内容を振り分けたい、この定数やマクロの意味などを説明したい、あるいは一時的に処理を無効化したいなどに使われる。これらは実際のコンパイルではなかったものとして扱われて、処理には影響しない。

一方、人間側にとっては、開発におけるヒントに当たるようなものであるため、それが正確かどうかで開発でのミスリーディングの誘発を招く可能性が出たり、開発効率にも影響を及ぼしてしまうこともある。特にコメントに嘘や間違いがあった時は間違った変更を加えてしまい、事態をより悪化させてしまう場合もある。したがって、有害なコメントがあるくらいなら、ない方がマシということにもなる。

また、最近ではgitをはじめとしたバージョン管理システムやそれに関連する作業ツールがあるため、そのコメントで変更内容と理由を把握することもできる。この場合はその変更内容をしっかり書くことが必要になる。

なお、私の場合は基本的にソースコードにコメントを書かないが、当然ながら例外もある。

まずは、複雑な処理をどうしても記述しなければいけない時にそれを簡単に説明する場合、あるいはフレームワークやライブラリーに起因するバグを回避する際にその旨を説明する場合、あるいはコンパイルレベルで処理を変更するような一種のフラグを立てる場合などである。これらはユーザー側からは見られないようにしたいが、開発者側には注意喚起と説明として書いている。

もう一つは、ドキュメント化を前提としたコメントである。これは、JavaDocやHeaderDoc、Doxygenなどに代表される、メソッドの定義部分に所定の書式に従ってコメントを使って処理の内容や引数の意味、及び返り値に関する説明を行うものである。基本的にはこれは引数が変更されることはそれほど多くないこと、定義や設計レベルに関わるものであるため、修正を加える際はこのコメントにも目がつきやすいという点も大きい。また、最近のIDEではこれを利用してメソッドや変数・定数を説明するものも多いため、これについては開発効率上導入するのが望ましいと考えている。

上記の例外はあるものの、基本的にはコメントがなくても十分理解できるようなコードを作成することが望まれる。もちろん、必要に応じてコメントを書くことは悪いことではないが、過剰なコメントや、間違いのあるコメントは有害な点は気をつけたいところである。