ソースコードのコメントを書こう

はじめに

私はコメントをよく書く人です。
書かないと気がすまない。
そんな人の意見として読んで頂ければと思います。

コメントを書く/書かないの論争でよく言われているのは
「コメントを書かないと読めないようなコードを書くな」
というものです。

これは、コメントを書かない人の意見として言われているものですが
本当に良いコードを書けばコメントは不要なのでしょうか？
私はそうは思いません。

英語が読めない

プログラミングは変数名、メソッド名等、英語でかかれている事がほとんどです。
たまにローマ字で書いているものもありますが
特別な理由がない限り、それこそ良くないコードだと思います。

日本人には、英語が読めない人も多いと思います。
こういう時、日本語でコメントが書いてあるのは良いのではないかと思います。
(でも英語はちゃんと読めた方が良いです。私はあまり読めないですが・・・)

修正箇所の特定が容易

例えば「開始する」というボタンを押した時の動作を追加したいと思いました。
コメントで「開始するボタンの処理」とか書いてあれば
grepで「開始する」を検索するだけで、目的のコードが見つけやすいはずです。

もし、コメントが書いてない場合は、

1. その画面のレイアウトが記載されいているファイルを探す
2. レイアウトから「開始する」ボタンを見つける
3. ボタンを押した時に呼ばれるコールバック関数を探す
   という手順を踏む可能性があり、目的のコードにたどり着くまでに幾分か時間がかかってしまいます。

見栄えが良い

これは意見が分かれる所かもしれませんが、パッとコードを見た時の見栄えが良いのではないかと思います。
コメントが非常に少ないコードの場合、コードを読む気がなくなってしまいます。

とあるメソッドを実装しようとした場合、そのメソッドに求められる機能を実現するためには

1. Aして
2. Bして
3. Cした結果を返す
   のように、いくつかのステップに分かれる事が多いと思います。

それぞれのステップの先頭にコメントが書いてあれば
こういうステップで実現している事も分かりますし
処理ごとの区切りがはっきり見通しやすいです。

ソースコード レイアウトの統一化が図れる

C++やJava等、クラスが扱える言語はコンストラクタが存在するはずです。
そのコンストラクタでは各初期化処理が行われますが
例えば、画面表示用のクラスの場合、メンバ変数の初期化をしたり、UIパーツへどのような値を表示するかの設定を行うかもしれません。
(UIクラスはUIがロードされる際のメソッドがあるからそこでやった方が良いとかは、ひとまず置いておいて・・・)

自分はコンストラクタで

1. メンバ変数の初期化
2. UIパーツへの表示設定処理
   という順番を守って処理を行っているとします。

public HogeClass() {
    // メンバ変数初期化
    mData1 = 0;
    mData2 = 5;

    // UIパーツへ表示を反映
    mTextField1.setText(mData1);
    mTextField2.setText("あいうえお");
}

そうした時に、上記のようにコメントを書いておくと
別の人が新しい画面を追加してクラスを作った場合、この順番に従って書いてもらえる可能性が高まり
結果、どの画面クラスのコードも、同じようなコードレイアウトになって見通しがしやすいコードになります。

コメントは簡潔に

長いコメント、主に複数行に渡るコメントはやはりコードの見栄えとしても悪くなってしまいます。
コメントは簡潔に書きましょう。

ただ、コードを見た時に「何故こんなことしているの？」と思ってしまう処理を止む無く書かなければいけないこともあります。
そういう時は説明として長くなってしまう事もありますので、その場合は仕方が無いと思います。

関数コメントも書こう

Javaでは、JavaDocでヘルプを生成するためにメソッドの先頭に特定のフォーマットに従ったコメントを書く事があります。
Javaに限らないですが、これは是非やった方が良いです。
細かく引数や戻り値の説明だったり書くのは手間ですので、省略することもありますが
関数コメントを書くことで、これもメソッド間の区切りが分かりやすくなり、コードの見通しが良くなると考えます。

終わりに

ソースコードの書き方というのは人それぞれで宗教論争のようなもので、その中にはコメントの是非も含まれます。

ただ、コメントを書かない理由を探すのではなく、書くことでメリットはこんなにあるんだよ。と探す方が楽しいですし
コード自体もより良いものを書くことができるようになるのではないかと思っています。