プログラミング覚書

良くない設計書の記述例

私が読んだ悪い設計書の例を書いてみます。

それは、EXCELでA4横のものでした。IT業界では、このEXCELでA4は多いです。

■長すぎる1行

EXCELでA4横ですと、1行の文章を長くできますが、長すぎると読みづらいです。

人間が物理的な1行で確実に読み取れる文字数には限度があります。

■基本的なこと、大切なこと、共通なことが後に記述

物事、基本的なこと、大切なこと、共通なことは前に書くべきです。読む場合、途中から読んだのでは、つながらない、意味がわかならないことあるため、普通は前から読みます。

また、全部は読まなくても最初の方は読みます。ですから基本的なこと、大切なこと、共通なことは最初に方に記述すれば読んでもらえます。

■大切なことを短い文で記述

文があまりに短いとその言っていることもあまり重要ではないと読み手は思いがちです。
その場合、文字を大きくする、色をつける、多少を文を長くするなどの工夫し、重みをつけると気をつ
けてもらえます。

こんな設計書を書いたため、複数の読み手が読み漏らし、実装が間違いその修正に時間と多大なお金が
かかったプロジェクトを経験しています。

個人が読み漏らしすれば、その個人が問題がある可能性がありますが、複数の人間が読み漏らしすれば
やはり、設計書の記述方法が問題ありと判断するのが正しいと思います。

基本設計書には人と時間をかけるべき

ソフトウエアの開発で基本設計書は、詳細設計書、プログラムコード、試験仕様書の元になります。

また詳細設計書、プログラムコードの量的な面は基本設計書よりも多くなります。

このため基本設計書にあいまい、ゆれ、矛盾、お茶を濁した記述、表現方法の問題があると、詳細設計書

詳細設計書、プログラムコード、試験仕様書もそれらを引き継ぎ、結合試験以降に問題が発覚します。

もちろん詳細設計書を作る過程で基本設計書の問題は修正されますが、程度問題であまりに問題が多い

と詳細設計書、プログラムコード、試験仕様書に問題が引き継がれます。

したがって基本設計書を作る過程で多くの人と時間を割り当てるべきなのですが、基本設計書は基本的

あまり細かいこと具体的なことは書かないことからあまり人、時間を割り当てない傾向があります。

しかし、基本設計書は正確に、事柄によっては具体的に、文章もより簡潔に、重要なことは目立つに

に書かないとそれ以降の過程のかかる時間、誤りが多くなり遅延やコスト増を招きます。

日本では、動くプログラムの品質はやかましく言いますが、基本設計書の品質についてはあまりいいま

せん。

IT業界は、文章を書くことが依然として個人の技量、裁量の域を脱していないことが多いです。

顧客の要求は無理難題でないのに芳しくないプロジェクトは基本設計書の品質に問題がある場合が多い

ようです。

IT業界の設計書は下手

IT業界における設計とは、ユーザの要求、要望にかなえるため、ハードウエア、ソフトウエア、運用を設

計することですが、事実上、それらを文章、図に表すということが仕事の半分を占めます。

ところがIT業界の設計書など上手なものはなく、むしろブログのほうが圧倒的わかり易い、表現が上手

ということが多いと思っています。

優れたブログ記事　＞＞＞＞　IT業界の設計書　です。

以下のようなまずさが顕著です。

・IT業界の設計書の文章など、受け取り側がどう受け取るかあまり考慮されていません。

自分の文章のあいまいさ、意味不明を棚に上げて読み手の読解力不足などどといっています。

・徹夜や残業で頭が蒙昧しているため、文章も蒙昧し意味不明、難解ものがあります。

・同じ理由で全体構成が下手な場合が多いです。

・目次、概要がなくいきなり内容に入った説明で初めての人、外部の人にはわかりにくいです。

IT業界の設計者にブログの特に上手と思われる記事を読ませ、こういう風に書けといいたいです。

私のお気に入りブログに文章が上手な人がいますが、彼（彼女）のつめの垢でも煎じて飲ませたいです！

もっともこのような記事を書いたのはIT業界の設計書の書き方に取り組んでみようかなと思いはじめて

いるからかもしれません。IT業界の設計書には大分悩まされてきましたから。

ソフト開発でお客様は神様か？

ソフト開発でお客様と開発者は主人と奴隷のような関係なことがあります。

ソフト開発でお客様の要求をなんでもを受け入れ、開発者に犠牲を強いる方針の会社があります。
これはなにもソフト開発に限ったことではありませんが、ソフトはある程度出来上がってくると使い勝手、問題点がわかり易いため、最初の打ち合わせ、合意になかった機能変更、追加を簡単にお客様から、「どう、やってくれない」と言われることがあり、責任者はそれをほぼ全面的に受けてしまうことが多いようです。

そのため開発者は午前様の上、土日は無しなどということがよくあります。

これは、お客様に要求もありますが、受け手側にそれを受けてしまうことが大きいと思います。

部長とか課長に思想にお客様のいうことはなんでも聞くことが、仕事の受注が続く秘訣だと思っているふしがあります。

しかし、開発者に過度の犠牲を強いることを続けると開発者がつぶれる、離反するという事態になり、トータルでうまくいないようです。

お客様と開発者の負担はほぼ半分になるか６：４の割合が正しいと思います。

神の存在を宣言しましたが、神からみれば片方に過度の負担がかかることは正しくない、良くないとされるはずです。
お客様と開発者が兄弟や親族であって場合には、負担は半分づつとするはずです。

これは、ソフトが作ってみないとわからないという点が大きいのですが.......
ここからは文芸春秋の記事からの受け売りなのですが、日本では、最初に明確かつ詳細に仕様書を作成しないで大まかな構想と予算と納期はあるから仕事をやってねというパターンが多いからのようです。
アメリカやインドでは、最初に精密は仕様書を作成するということらしいです。
また、日本は、行き過ぎた顧客優先ということらしいです。

私も、「大まかな構想と予算と納期だけ」の典型のプロジェクトをやったことがあり、仕様変更があまりにも頻繁にあり、極めて大変でした。
また、私も顧客のためなら、開発者を犠牲にしても良いという思想は良くない、正しくないと思っていました。

トータルでうまくいくには、お客様の要求をブロックできる、調整できなければならいと思います。

Eclipseが混乱？

開発言語がJAVAで開発ツールに総合開発環境であるEclipseを使っています。

Eclipseは、GUIベースで多機能かつ高機能です。ソースレベルでのデバックもできます。

ソースレベルでのデバックとはソースを表示しソースの1行単位でプロググラムを実行し動作を確認できることです。

しかし、あるシステムをEclipseのこのデバック機能を使ってプログラムがどのように動くが見ようと

したのですが、表示されてソースの1行単位の実行と実際の実行が一致しません。

コンソール出力しているにも関わらず出力されないので明確にわかります。

ソースとコンパイル結果のクラスファイルの不一致かと思われ、すべて再コンパイルしましたが、

状況は変わりません。

実は、このシステムは2つのバージョンがあり、同じファイル名のソースが２つあり、Eclipseが混乱

している、正しくソースを認識できない可能性あるとアドバイスをもらい、確認したら確かに同じファイ

ル名のソースが２つあり、Eclipseが正しくソースを認識していないことが確認されました。

実際に動かしソースで追跡できないのはつらい場合があります。

どうしたら良いか、ひらめきました。同じファイル名のソースは当然、別のディレクトリにありますが、

実際に動いるているソースを他方にコピーしました。そしたら、表示されるソースの1行単位の実行と

実際の実行結果が一致するようになりました。めでたしめでたしです。