【プログラム】コメント文があった方がいいプログラム・パターンを考えてみる

プログラム全般 / アルゴリズム

■ はじめに

 「コメントを書く派」と「コメントを書かない派」がいる。
個人的には、コメントは書いた方がいいと思うが、「コメントを書かない方がいい派」を言い分は
以下のような意見を聞いた。
「コメントを書かない方がいい派」の意見 
 [1] 可読性のあるプログラムであれば、コメント文は必要ない
 [2] コメント文のメンテができていないため、記述が古いコメント文残った場合、
　　 ソース調査時に読み誤る可能背が出る
 [3] コメント文を無闇に書くと逆に読みづらい

etc...

ただ、そんな時でもあった方がいいのでは？ってコメント文をまとめてみる

■ コメント文が必要ではないかと思うパターン

 * コメントを書かないと「意図的」か「ミスってるのか」が、判断が難しいに付けた方がいいと思う
　→ コメント文を書いておけば、意図的に実装しているのが分かるため

【1】switch文で意図的に何もしない場合/(C言語等であれば)意図的にbreak文を書かなかった場合

イメージ：意図的にbreak文を書かなかった場合 
switch (type) {
   case 1:
      ...何らかの処理...
      break;
   case 2:
   case 3:
      ...何らかの処理...
      // go through（breakせずに、意図的に「case 4」の処理に行う）
   case 4:
      ...何らかの処理...
}

【2】例外が発生することを見込んだ処理をしている場合

 * 例外処理の場合、例外を再スローするかorそれとも例外を意図的に潰して飲み込んでしまうかに分かれると思うが
   「例外を意図的に潰して飲み込んでしまう」ことをコメント文に書いておけば、意図的に実装しているのが分かる
イメージ：意図的にbreak文を書かなかった場合 
// 文字列がInt型の数値であるかどうかを判定するメソッド
//  引数が数値でない場合(例えば「value=abcd」)、例外が発生することを想定している
public static boolean isIntNumber(String value) {
  boolean isIntNumber = false;
  try {
    int number = Integer.valueOf(value);
  } catch (Exception ex) {
     // Eat it up
  }
  return isIntNumber;
}

■ メモ

http://www.atmarkit.co.jp/fdotnet/vblab/bizappbasic01/bizappbasic01_02.html
 * 「命名のコツ」「コメント記述のコツ」などは一読した方が良さそう
    (以下は、一部、記載してみる、多分、「コメントを書かない方がいい派」はここまでは遣り過ぎって思うんだろーが)

コメントは、業務上のどんな処理をしているのかを記述する

 * 業務上で使われている単語に置き換えるだけで、画面上でどんな操作をしているのか、
  または業務上のどんな処理をしているのかが明確になる
メリット 
 * 変更に強いアプリを作るのに有効
 => 上からコードを読むと、変更が必要な個所を見つけるのに時間がかかる
 => 一方、コメントで具体的に何をしているかを記述してあれば、必要個所が比較的にすぐ見つけ易い

関連記事

【C#】コーディング規約

http://blogs.yahoo.co.jp/dk521123/28877963.html

【VB】コーディング規約

http://blogs.yahoo.co.jp/dk521123/25331012.html
http://blogs.yahoo.co.jp/dk521123/25354394.html

【プログラム全般】良いプログラムを書くために...

http://blogs.yahoo.co.jp/dk521123/29342942.html