よくないプログラムコメントの書き方について

プログラムのコメントというのは、人によって書き方は様々である。

2008年07月30日 otsune コードでhowやwhatは書けてもwhyは表現できません！はてなブックマーク - Latest topics > ドキュメントは善か悪か - outsider reflex

と、otsune さんも言うように、俺が考えるプログラムのコメントというのは、「summary」や「why?」を書くべきであって、決して「what?」をひたすら書くべきではない。
(この場合の「summary」というのは、「what」の概要のようなものかもしれないし、コーディングの思想のようなものかもしれない。そして、「why」は、仕様的な「何故」かもしれないし、トリッキーな方法を説明する為の「何故」かもしれない)

そもそも、「如何に(後に役に立つ)ドキュメントを残すか」や「プログラムにどのようにコメントを書くか(又は書かないか)」というのは、延々と議論が繰り返されているテーマであり、別にその正解を提示しようとする訳ではなく、あくまで個人的な意見であることを書き加えておく。

という訳で、今回は俺があまり役に立たないと思うようなコメントをあげてみよう。

イヤなコメントの付けかたの例

例1)

/* a に b を代入 */
int a = b;

読めばわかる。


例2)

// モードが MODE_XXX で フラグが 1 でなく、kbn が 1 又は 2 の時
if (((mode && MODE_XXX) == MODE_XXX) &&
    (flg != 1) &&
    (kbn == 1 || kbn == 2)) {

読めばわかる。
(逆に「何故」そのような判定なのかがわからない)


例3)

try {
  // DBコネクションを取得します
  conn = DB.getConnection();
  // トランザクションを開始します
  tran = conn.begenTran();
  // SQLを取得します
  String sql = this.makeSQL();
  // SQLを実行します
  int ret = conn.execute(sql);
  // コミットします
  conn.commit();
  // 処理結果を返します
  return ret;

// 例外を補足します
} catch(Exception e) {
  // ロールバックします
  if (conn != null) { conn.rollback(); }
  // ログを出力します
  LogHelper.writeError(e);
}

まるで古文か英文の原文と口語訳のように説明書きがある。
(ロジック読みにくすぎ。どうしても説明したいなら、メソッドの先頭かブロックの先頭で summary にするべき)


まぁ、他にも
・ 書いてあるコメントが間違えている
や
・ コメント情報が古くて最新の状態を反映していない
などもあるのだが、これでも「ないよりマシ」なモノもあるため、一概にはなんともいえない。

プログラムのコメントというのは、遊びで作るプログラムや、利用目的がはっきりして比較的小さなプログラムなどには、Summary 以外ほとんど必要ないと思うのだが、どうしても業務プログラムや大きなプログラムになってくると必要になってくるものである。
しかし、書くとなっても、「仕様書」に書いてあることと重複してダラダラ書いても意味がないし、かといって全く仕様を書かないとなると「仕様書がどこまでメンテされているのか」ということも影響してくる。

自分自身、これからもプログラムを作る時は(今までも気をつけてはいるが)、プログラムのコメントのみならず、如何に生産性・品質・保守性などを効率よく行うことができるか。如何に他人に情報を伝達することができるか。などを考慮しながら取組みたいものである。

特に大人数が関わるプロジェクトなら尚更です。