Diary?

(11:42)

昨日書いたことの続きといえばそうかもしれないけど、いわゆる「プログラム設計書」について。それでこの「プログラム設計書」の定義が人によってちとバラバラな事があるので、ここではプログラムの各行をそのまま日本語化したようなドキュメントと定義する。例えば次のようなソースコードと Javadoc だ。コードの中身は適当なんで、そこには突っ込まないでくれ。

/**
 * ＜概要＞
 * <ul>
 * DB を検索して FooBar テーブルのエンティティを返す API。<br>
 * </ul>
 * <処理内容>
 * <ul>
 * ・Connection, Statement, ResultSet それぞれのワーク変数を null 値で確保する。<br>
 * ・DBUtil.createConnection でコネクションを取得し、 conn に設定する。<br>
 * ・DBUtil.createStatement でステートメントを取得し、 stmt に設定する。<br>
 * ・stmt.execute で検索操作を実行し、結果を rs に設定する。<br>
 * ・rs を FooBarEntity のコンストラクタに渡し、そのエンティティを返す。<br>
 * ・処理途中で例外が発生した場合
 * <ul>
 * ・メンバフィールド logger の error メソッドでログ出力を行う。<br>
 * ・null を返す。<br>
 * </ul>
 * ・例外の発生の有無に関わらず、 DBUtil.close に conn, stmt, rs を渡し、後処理をする。<br>
 * </ul>
 * <br>
 *
 * @param key テーブルの検索キー
 * @return Foobar テーブルのエンティティ
 *
 */
public FooBarEntity search(String key) {
  Connection conn = null;
  Statement stmt = null;
  ResultSet rs = null;
  try {
    conn = DBUtil.createConnection();
    stmt = DBUtil.createStatement(conn, "Entity", key);
    rs = stmt.execute();
    return new FooBarEntity(rs);
  } catch (Exception e) {
    this.logger.error(e);
    return null;
  } finally {
    DBUtil.close(conn, stmt, rs);
  }
}

この Javadoc のフォーマットはとあるプロジェクトでマジに使われていた奴をちょっと変えたもので (実物はもっとタルいフォーマットだった)、似たようなフォーマットがゴロゴロしている可能性は十分にある。そしてもしもそうだった場合、途方もない労力が浪費されていることになる。最悪の場合はプログラム設計書が Word や Excel などで書かれている場合もあり、その場合は Javadoc バージョン以上にメンテナンスに手間が掛かる。もっともそのプロジェクトでは納品する時に Javadoc の HTML ファイルを手作業で PDF に変換させられていたので、どっちもどっちはであったが。

それで上記のプログラム設計書の何が問題かというと、＜処理内容＞に書かれていることがそのまま全部ソースコードに書かれていることの引き写しであり、つまりこれは二重管理だ。二重管理が一体どれほど愚かな事かはよほどの白痴でもない限りわかるはずなので、ここでは詳しく書かない。

じゃあその悪しき二重管理が何故行われるかだが、その背景は三つあって、そのうちの一つは日本語で書いた方がわかりやすいという驚異的にバカな誤解だ。何故それがバカなのかというと、プログラミング言語で書かれたソースコードを曖昧さのないように自然言語に変換する事は困難だからだ。例に出したソースコードではどこからどこまでが try 文のかかる範囲なのかが明示されておらず、その点について解釈がずれる可能性は十分にある。また、 finally 文を使う事を読み取れというのも無理な話で、次のようなソースコードも十分考えられる。

FooBarEntity entity = null;
(中略)
  entity = new FooBarEntity(rs);
} catch (Exception e) {
  this.logger.error(e);
}
DBUtil.close(conn, stmt, rs);
return entity;

もちろん規約をガチガチに固めることで防ぐことは出来るが、それが効果をあげるかどうかは極めて疑問だということを昨日の日記では書いた。そしてどれだけ厳しい規約で記述方式の統一を図ったところで、自然言語で記述する故の不自然さや曖昧さからは逃れられないだろうし、曖昧さを排除すればするほどプログラミング言語のキーワードを日本語に置き換えただけになっていき、自然言語の文章ではなくなる。

また、今回は try, catch, finally だけしか使っていないが、これがもしも条件分岐やループのネストが起こったとしたら一体どのような惨状になるのか検討もつかない。そしてこうやって厳しいルールで縛らなければいけないレベルの連中が書くコードは本当に凄まじく、一つのメソッドが数百行とか平気で書いてくる。そんな状態でプログラム設計書を書かれて、それ検証できるのか?

もしもこのようなプログラム設計書を読むに耐えうるレベルに持っていくとするなら、それこそしっかりとした構造化のされたソースコードにする他ない (それでもあやしいが)。ところがそういったコードを書けるレベルの技術者に関しては、やたらと厳しい規約がむしろ足かせになってしまう。

二つめの背景はプログラム設計書を書く奴と実際にコードを書く奴が別というものだ。俺のチームはそんなバカな事はやっていなかったが (一応精鋭部隊だった。あれで精鋭部隊かよと情けなくなるが)、他のチームではむしろそれが当たり前だった。こうなってくると、たとえプログラム設計書の書き手がどんだけ構造化を推し進めようとしても、実際にコードを書く奴がさっぱり理解できないという事態に陥る。自然言語とプログラミング言語の間に横たわる断絶を考えれば、プログラム設計書をそのままソースコードに落とし込むなんていうのは夢物語で、結局はコーダーのレベルに合わせざるを得ないこともある。

それにプログラム設計書の書き手が高いスキルの持ち主かというとそうとも限らず、例の 10 年泥のおっさんがいっていた「必要なのは業務ノウハウ。技術力は必須ではない」というのを真に受けたようなバカチンもいて、そういうのがスパゲティ設計書を書き始めるのだ。

そして三つの目の背景だが、これが恐らく一番の害悪で、それは日本語で書いてやらないと検証できないという終わっている奴が検証過程に入り込んでいるのだ。これについては結構確定的な証拠があって、本来クライアント側で決めなければいけない仕様のうち、 Java のノウハウが必要なものについては俺に丸投げされたことがある。なので、あちらのメンバーに Java の知識がそれほどなかったというのが一番考えられるケースだ。そういった人間がプログラムの詳細部分にまで口出ししなきゃいけない状況というのはどう考えてもクレイジーだ。

結論としてはこのようなプログラム設計書の存在自体が間違い。釈明の余地なし。開発中に作られるドキュメントには、それが何であれ、誰が何のために読むのかが定義されている必要があり、そしてプログラム設計書の場合は

誰が?

程度の低いコーダー、プログラムの事がわからん奴

何のために?

コーディング (製造とも呼ばれる)、コードの検証

となっており、要するに開発の現場から叩き出した方がいいバカのためにあるわけだ。じゃあ何でこういったバカが開発に携わっているのかというと、

• とにかく人手不足で猫の手も借りたい状態
• 末端のコーダーのレベルでシステムに影響があるなんて思っていない

これが理由だろう。前者に関しては、使えない奴にヘルプを仰ぐぐらいなら猫を連れてきて癒し要員にした方がマシだ。後者に関しては、そのコーダーのやらかしたヘマがとあるサブシステムのアーキテクチャーを根本からぶち壊していて、俺が一次請けに頭下げながら辻褄合わせしたことがあり、つまり使えない奴にコードを書かせちゃダメなんだってことだ。他にも別の会社の落ちこぼれからの質問に答えていたせいで俺とか別チームのリーダーの仕事が阻害されたとか、そういうところでも使えない奴のもたらす弊害は大きい。

もういい加減こういう不毛な事は終わりにしてくれと思うんだがなあ……。

(19:39)

「百万ゴールドの男」を読んでいたら、せっかくの休日が潰れてしまった。いわゆる制限プレイをする人ってのは結構多いけど、それをこうやってリプレイ記録の設定に使うってのは聞いたことがなかったな。凄い発想だ。

あと俺は親父が 5000 万とかいう借金抱えておっ死んで、危うくそれを相続するところだったからな。妙なところで感情移入しながら読んでた。