プログラムの翻訳コメントは要らない

プログラムをそのまま日本語に訳したようなコメントは無意味です。

処理の内容をそのままコメントに書いても、後から読むときに何の助けにもなりません。

例えば、このサンプルのコメントは一見丁寧に書かれているように見えますが、よく見ると、プログラムを読めばすぐ分かることしか書かれていません。

// もしvalidateResultFlagがfalseだったら、処理を終了する
if (!validateResultFlag) {
    return;
}
// phoneNumberListの件数分、ループする
for (int i = 0; i < phoneNumberList.length; i++) {
    // 空文字でなければ、メソッドhogeを呼び出す
    if (!"".equals(phoneNumberList[i])) {
        hoge(phoneNumberList[i]);
    }
}

 

このようなコメントはプログラムを日本語に翻訳しただけ、言い換えれば漢字にフリガナを振ってるようなものです。

確かに、技術書やネットに載ってるサンプルコードのコメントはこんな感じですが、それは、コメントの目的がプログラムの文法や書き方を説明するためだからです。

実際のプログラムのコメントはそのような説明文ではなく、プログラムを読んだだけでは分からない情報を書くべきです。
プログラマーなら誰でも一瞬で分かるような情報は邪魔なだけです。

 

先ほどのサンプルですが、まず前半部分はこのようになります。

// もしvalidateResultFlagがfalseだったら、処理を終了する
if (!validateResultFlag) {
    return;
}

// もし入力値チェックでエラーだったら、処理を終了する
if (!validateResultFlag) {
    return;
}

 

これならデバッグの際に、validateResultFlagに何が入っていて業務仕様上どういう場合にfalseになるのか、ソースを遡って調べなくても分かります。
逆に、「validateResultFlagがfalseだったら」という判定をしてることはプログラマーなら誰でも一瞬で分かるはずなので書く必要性はゼロです。

 

同じ考え方で、後半部分はこうなります。

// phoneNumberListの件数分、ループする
for (int i = 0; i < phoneNumberList.length; i++) {
    // 空文字でなければ、メソッドhogeを呼び出す
    if (!"".equals(phoneNumberList[i])) {
        hoge(phoneNumberList[i]);
    }
}

// 入力された電話番号を一件ずつ処理する
for (int i = 0; i < phoneNumberList.length; i++) {
    // 電話番号が未入力でなければ、DBに登録する
    if (!"".equals(phoneNumberList[i])) {
        hoge(phoneNumberList[i]);
    }
}

 

ここで一番のポイントは、「メソッドhogeを呼び出す」の部分をどう書き直すかです。
メソッドを呼んでいることは、コメントが無くても一瞬で分かります。
それよりも、何のためにそのメソッドを呼んでいるのかをコメントに書いておけば、呼び先のソースをわざわざ毎回読まずにすみます。

間違えないで欲しいのは、SQLを発行するとか、DBのテーブル名といった、呼び先の処理内容は書かなくていいということです。
「何のためにそのメソッドを呼んでるか」が分かれば十分です。

例えると、「リモコンのボタンを押して、テレビの電源を入れる」みたいな感じです。
何のためにボタンを押したかの情報は必要ですが、実際に電源が入る仕組みまでは意識しなくて良いのと同じです。

 

今までの内容をまとめると、サンプルの修正後はこんな感じになります。

// もしvalidateResultFlagがfalseだったら、処理を終了する
if (!validateResultFlag) {
    return;
}
// 入力された電話番号を一件ずつ処理する
for (int i = 0; i < phoneNumberList.length; i++) {
    // 電話番号が未入力でなければ、DBに登録する
    if (!"".equals(phoneNumberList[i])) {
        hoge(phoneNumberList[i]);
    }
}

 

コメントは単純にプログラムの内容を書けばいいというものではありません。
どのような情報があればプログラムをよりスムーズに読めるようになるか、見直してみてはいかがでしょうか。




コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です