2005年05月30日

コメントの鉄則

前回の記事を書いた後でコメントを書く場合の基準について質問を受けました。 そこで今週はコメントの鉄則について解説します。

コメントの鉄則はシンプルです。
「コメントにはプログラマーの思考を記述する」

言葉だけでは分かりにくいので具体例として前回のコードを修正します。stateの値としてWARNINGを追加します。

/**
 * 状態チェック
 * @param state NORMAL:正常 WARINING:警告 ERROR:異常 UNKNOWN:不明
 */
public void checkState(int state){
  switch( state ){
  case NORMAL:
    execNormal();
    break;
  case ERROR:
    execError();
    break;
  default:
    execUnknown();
    break;
  }
  ...
}

switchではdefaultでUNKNOWNとWARNINGを処理しています。UNKNOWNとWARNINGは処理が変わらないからまとめたのか,WARNINGの場合の処理を漏らしたのかは,このコードだけでは判断できません。
特にdefaultで実行するメソッドがexecUnknownとなっており,UNKNOWNの場合しか想定していない気がして不安になります。筆者だったらexecUnknownのコードを読んで問題ないことを確認します。
では次のコードではどうでしょうか。

/**
 * 状態チェック
 * @param state NORMAL:正常 WARINING:警告 ERROR:異常 UNKNOWN:不明
 */
public void checkState(int state){
  switch( state ){
  case NORMAL:
    execNormal();
    break;
  case ERROR:
    execError();
    break;
  default:
    // WARNING,UNKNOWNを処理
    execUnknown();
    break;
  }
  ...
}

コメントにWARNINGも想定してあることを明記していればソースだけで判断できます。 コメントには処理内容を記述するのではなく,プログラマーの思考を織りこんだほうが理解しやすいコードとなります。

「コメントにはプログラマーの思考を記述する」

これを忘れないでください。
逆に処理そのものをコメントにするのは無駄です。前回の解説のようにコメント自身がトラップに変化する場合もあります。



posted by まる at 23:45| Comment(0) | TrackBack(0) | プログラマ Chips | このブログの読者になる | 更新情報をチェックする

2005年05月23日

詳細仕様書,コメントによるトラップ

詳細仕様書を作成した場合の注意事項として,詳細設計書とソースは常に一致させることが挙げられます。
ソースはデバッグや保守の段階で頻繁に修正されます。ソースを修正した場合は詳細仕様書も見直さなければなりません。しかし,詳細仕様書の存在を忘れていて更新を忘れたり,更新する余裕がなく更新しなかったりします。コメントも同様です。ソースは直してもコメントを直さないというものよく見ます。
筆者はこれを詳細仕様書,コメントによるトラップと考えています。

詳細仕様書のトラップはソースを読めば回避できることが多いのですが,コメントのトラップにはよくひっかかります。

過去に見たコードの例を挙げます。

/**
* 状態チェック
* @param state NORMAL:正常 ERROR:異常
*/
public void checkState(int state){
  switch( state ){
  // stateはNORMALとERRRORのみ
  case NORMAL:
    execNormal();
    break;
  case ERROR:
    execError();
    break;
  default:
    execUnknown();
    break;
  }
  ...
}

コメントにはNORMALとERRORしかないと書いてありますし,パッと見るとNORMALとERRORしか処理していないように見えます。しかし,switchの分岐に default があり,defaultでexecUnknown()を実行しています。このコードを書いたプログラマは,stateの値としてUNKNOWNを追加したのにコメントを修正していなかったのです。

この程度の短いプログラムであればひっかからないでしょう。

しかし,複雑なソースに仕込まれた場合,思考能力の落ちた状態(例:徹夜の最中)ではコメントのトラップに騙されてしまいます。徹夜は生産性を落とすという例の一つですね。
なるべく元気な状態で作業をしたいものです。

posted by まる at 22:58| Comment(0) | TrackBack(0) | プログラマ Chips | このブログの読者になる | 更新情報をチェックする

2005年05月16日

詳細仕様書

今回は詳細仕様書について説明します。

詳細仕様書ではクラス/関数といったプログラム内部のインタフェースを説明します。
要求仕様書から詳細仕様書までが完璧に記載してあればドキュメントだけでシステムの全体が把握できます。


納品物がライブラリの場合はクラス/関数そのものが外部とのインタフェースになりますので,使用者が必要とするクラス/関数の仕様は機能仕様書で行います。
詳細設計書はプログラマーの保守用のツールという意味合いが濃いため割と適当に書きます。そもそも詳細仕様書を書かない場合もあります。
最近ではdoxygenjavadocといったソース中にコメントを書けば勝手にドキュメントを作成してくれるツールがあります。おかげで昔より詳細仕様書を書くことが減りました。

詳細仕様書の記述内容は書かなくても分かるとは思いますが,いちおう書いておきます。

・クラス名
・クラスの目的
・関数名
・関数の戻り値の説明
・関数の引数の説明
・関数の処理の概要

具体例としてはSunのJ2SEのAPI仕様などを参考にしてください。
例に挙げたJ2SEのAPI仕様まで記述できれば詳細仕様書として文句なしですが,一般的にはそこまでのコストを詳細仕様書に費やません。J2SEのAPI仕様の場合は顧客へ提供物がライブラリなので,API仕様自体が機能仕様書にあたります。だからあそこまで丁寧に記述してあるわけです。
posted by まる at 23:39| Comment(0) | TrackBack(0) | プログラマ Chips | このブログの読者になる | 更新情報をチェックする

2005年05月09日

機能仕様書(その2)

GWのため一週間のお休みをいただきました。
GWはシステムを停止させてもあまり問題とならない数少ない期間の一つなので「GW?なにそれ?」という具合に働いた人も多かったと思います。
筆者は幸運なことに今年は世間どおりの休みをいただきました。
人の休みのときに休めるっていうのはいいですね。去年のGWは400h/月の超過労働のまっただなかで地獄の淵を覗いていただけに喜びもひとしおです。
本文が書きづらいので無駄なしゃべりが増えてますね。いいかげん本題に入りましょう。

機能仕様書にはシステムとしての入出力を記述します。

プログラマーの観点で考えるとプログラムの入出力がエラーケースも含めて漏れなく記述されている必要があります。機能仕様書どおりにプログラムを開発すればプログラマーの責任を果たしたことにできるので。「プログラムの入出力をエラーケースも含めて漏れなく記述する」というのはSEにとってものすごく大変です。
入出力のパターンのうち全体の80%を網羅する場合に1時間かかったとすると,90%では5時間,95%では20時間といった具合に指数関数的に労力が増大します。
そのため,SEは機能仕様書をプログラマーにフクロにされない程度に手を抜くかを考えます。
SE=プログラマーの職場では後述の詳細設計書はもちろんのこと,機能仕様書もほとんど作成せずにいきなりコーディングに入ります。仕様を考える人=プログラマーであれば意思の疎通を図る必要がないからです。
SE≠プログラマーの場合は両者の能力により記述レベルが決まります。
SEの能力が高く,プログラマーの能力が低い場合は機能仕様書は詳細に記述します。プログラムの入出力は当然として,アーキテクチャの説明,設計思想なども記述するでしょう。一方,SEの能力が低く,プログラマーの能力が高い場合には機能仕様書は荒い内容となります。プログラムの入出力も顧客からの要望が記載されているだけです。エラー時の対応方針なんてカケラも記載していません。そもそもSEが思いついていないんですから。入出力の仕様にも矛盾があるので油断できません。
SE,プログラマー共に能力が高い場合はお互いに分かっているもの同士なので,両者の力関係や忙しさ,会社間の契約によって決まります。
SE,プログラマー共に能力が低い場合は荒い仕様書をもとに下手なプログラムを作るのでテスト工程以降で不具合が多発してデスマーチ送りとなります。

機能仕様書,詳細設計書の時点で設計を怠ると後で仕様不良となって大きな手戻りとなって返ってきます。すぐにコーディングに入りたい気持ちも分かりますが設計はちゃんとしましょう。
posted by まる at 23:31| Comment(0) | TrackBack(0) | プログラマ Chips | このブログの読者になる | 更新情報をチェックする

広告


この広告は60日以上更新がないブログに表示がされております。

以下のいずれかの方法で非表示にすることが可能です。

・記事の投稿、編集をおこなう
・マイブログの【設定】 > 【広告設定】 より、「60日間更新が無い場合」 の 「広告を表示しない」にチェックを入れて保存する。


×

この広告は180日以上新しい記事の投稿がないブログに表示されております。