ソフトウェア開発201の鉄則 原理95:コーディング:コードを仕上げる前にコメントを加えよ

要旨

* プログラム実行を与えないことを理由に、ソースコード中にコメントを書かないプログラマがいる
* が、ソースコードのコメントは、後に容易にデバッグ、テスト、保守、進化をさせるのに役立つものだ
* なので、コーディング中には、こまめにコメントを書き加えよう

解説

これは、ほとんどのソフトウェア開発者が、わかっていることだろう。頭では。

それでも、どうしても手間が先に立ち、億劫になってしまうものだ。ソースコードは書かなければ、所望の動きにならないから端折れない。一方、コメントは、書かなくても動作や品質に影響を与えない。そう考えがちでだ。

それが、違うんだな。

コメントも、ソースコード

こう考えた方が、いい。実際、ちゃんとしたコメントの有無は、後々の不具合解決や進化に大きく影響を与えるのだ。

この原理に書いてある例を出すと、

アルゴリズムをコードで表現するところが間違っているのであれば、コードだけ直せばいい。アルゴもコードも間違っていたら、コメントとコードの両方を変更するべきだ。この時、コメントがなかったら、どうやってアルゴリズムの間違いを発見するのだろうか。

そう。わからない、のである。特に、実装者以外が見たときに。

それがわかっていたとしても、コメントを書くのは、やはり億劫なものだ。それをなんとかするには、次のようなことを心がけると、良い。

まず、コードを書いているときにコメントを書こう。

動くものができたら、心境として、あー終わった、となるものだ。それからコメントを書き入れる気分には、なかなか、ならない。

それに、気分より大事なこと。動いているものは、なるべく変更しない方がいい。コメントを書いているときに、ついコードをいじってしまう可能性がある。

原理では「仕上げる前に」と書いてあるが、普段からこまめに、が正解。

次に、書く量を減らそう。

この原理と矛盾するかもしれないが、要は、コードと合わせて「読みやすく、理解しやす」ければいいのだ。

他の原理にもあるが、変数名、関数名は意味のある、わかるものをつけようとか、インデントは深くしないこと、とか、諸々がきちんと守れられて、読みやすいコードであれば、わざわざコメントを入れる必要は、ない。

例えば

getTemporaryData()

という関数に、"Getting temporary data" というコメントは不要だろう。関数名から容易に想像つくので。

コメントを書き入れる必要があるのは、大きくいうと、3つだろう。

まず、コードだけではどうしてもわかりづらいところを、コードの補足として。

もう一つは、アルゴリズムの説明。選択したアルゴとその全体処理の概要が冒頭にないと、コードだけでは、まずわからない。

最後に、いくつか手法に選択肢がある中、とある手法に決定して設計、実装をした場合の、その選択の根拠。これは正しかろうがそうでなかろうが、そう決定した理由を書くべきだ。

コメントを書く内容や場面を限定すれば、だいぶ、やりやすくなるのではないだろうか。