パスワードを忘れた? アカウント作成
11945938 story
ソフトウェア

スラッシュドットに聞け:ソフトウェア開発の現場で設計書は必須か 205

ストーリー by hylom
ケースバイケース 部門より
あるAnonymous Coward 曰く、

先日、「ソフトウェアの開発における見積もり」が話題になっていたが、ふと設計書についても同様の事を感じていたのでタレコミしてみた。

以前大手SIでプログラマをしていたとき、自分一人のワンマンプロジェクトをいくつか持っており、それに加えてチームプロジェクトにプログラマとして参加していたのだが、自分のプロジェクトではプログラミング時に設計書を使う事はなかった。

いっぽう、チームプロジェクトでは設計書はあったが、内容は酷く古く、一貫性も無く、必要な情報が載っておらず、結局一番最初の開発以降、プログラムの改修時に設計書を参考にプログラミングをする人間は誰もいなかった。結果、素人の設計書通りに作られたチームプロジェクトのアプリケーションは駄作になり、私が設計書無しで取り組んだワンマンプロジェクトはどれも高い評価を受けた。

とはいえ、プログラムの完成後に設計書の作成を要求されたために設計書を書いた事は書いたのだが、無意味な時間だと感じて精神的に酷く苦痛を受けた。必要な事はコメントに書いてあるし、お望みとあらばドキュメント化して自動出力も可能にしてあったのだ。しかし、自動出力したドキュメントは「上司がわからないから」として却下された。

もちろん、非常に大がかりで詳細な仕様の共有を脳内で完結させるのが不可能な場合、設計書は有用なものだろう。しかし、たいして大きくも無いプロジェクトで、しかも設計者が素人となれば、設計書は有害なもの以外の何物でも無いと個人的には感じている。

皆さんはどの様にお考えだろうか。

この議論は賞味期限が切れたので、アーカイブ化されています。 新たにコメントを付けることはできません。
  • by boxfox (22352) on 2015年03月03日 17時08分 (#2771008)

    意外と目を通したことのある人は少ないんですかね?
    読みましょう、とりあえず。

    やさしい機能仕様 パート1: なぜわざわざ書く必要があるのか? - The Joel on Software [joelonsoftware.com]

  • 若いのう (スコア:4, 参考になる)

    by hinatan (24342) on 2015年03月03日 15時15分 (#2770910)
    仕様書はテストケース、サポート向けマニュアル、ユーザ向けヘルプの原材料にもなりますので必ず必要。

    あと若いうちは「設計書なんかいらねぇ!」って言えるかもしれませんが、
    年取ると(よぼよぼ・・)記憶力が衰えて1年前に自分の作ったものも忘れちゃう。
    ヤングでもとある文字列の validation規則なんて聞いても答えられない。

    なので仕様書は小さなプロジェクトでもまず「自分のために」書く。

    役に立つ仕様書を速やかに書けないというのなら単に能力が不足しているだけで、それを棚に上げて仕様書という道具のせいにしちゃいけない。
    • Re:若いのう (スコア:3, 興味深い)

      by Anonymous Coward on 2015年03月03日 15時53分 (#2770940)

      このコメントの人が、「仕様書」と「設計書」という言葉を混同して使っているのが気になりました。
      仕様書(外部仕様書、要件定義書)と設計書(詳細設計書)では、だいぶ意味が変わってくると思います。

      あと、特定のポイントに関する仕様or設計(元コメのvalidation規則などの)は必要でしょうが、
      だからといって、プログラムの処理全体を網羅的に文書化することが必要かどうかは別問題でしょう。
      このあたりの認識の違いで、ソースのコメントで十分かどうかの意見が分かれたりしているのでは。

      個人的には、仕様書は必要、設計書はテーブル設計書くらいは欲しいかな。

      親コメント
      • by Anonymous Coward

        仕様書(外部仕様書、要件定義書)と設計書(詳細設計書)では、だいぶ意味が変わってくると思います。

        そういうカテゴライズも、一般的かどうかは微妙ですね。 あるソフトウェアを作るための設計のアウトプットのドキュメントを「設計書」と言うなら、外部仕様書だって要件定義書だって設計書です。 「仕様書は書くけど設計書は書かない」と「要件定義書は書くけど詳細設計書は書かない」では、意味の伝わり具合にかなりの温度差があります。

    • by takaha4 (47140) on 2015年03月03日 18時58分 (#2771079)
      作ってくれって言われたやつを作ってるんだから、発注元が仕様書を作るべきなんだよね。
      テストケースも。このテストが出来たら合格とすると。
      客の要求が曖昧っていうのがこの業界の癌なんだよな。
      親コメント
      • by Anonymous Coward on 2015年03月03日 19時41分 (#2771110)

        私が関わっているプロジェクトだと
         要件・要望書…………………ユーザが書く
         要件定義………………………ユーザ企業SEが書いてユーザがレビューと承認
         概要(外部)設計書……………ベンダSEが書いてユーザ企業SEがレビュー、ユーザ承認
         詳細(内部)設計~結合試験…ユーザ側完全ノータッチ

        ですね(承認は簡略してますが)。
        その後の試験工程からまた関与しますが。

        親コメント
  • by Ay (33430) on 2015年03月03日 15時04分 (#2770899)

    DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。

    > しかし、自動出力したドキュメントは「上司がわからないから」として却下された。

    これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。

    • by Anonymous Coward on 2015年03月03日 15時30分 (#2770923)

      >もっと上流の業務寄りな文書って必要だと思う。

      ほんとこれ。
      「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」

      なぜなら「何をしているか」は分かっても「何をしたいか(したかったか)」がわからないから。

      極端に抽象化した話、
      X+Y =B
      しているのがわかっても、Xがなんなのか(リンゴなのか、速度なのか)、Bは何かわからなければドキュメントの意味がない。
      もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」

      これがわからんと意味がない。
      逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。

      親コメント
      • たとえば状態Aを、状態Bにするのが目的なアプリがあったとして、
        A → B
        ソースコードに書かれてるのは → の具体的な方法。
        → から A や B を炙り出して推測しないといけないから、だから他人の書いたソースコードって読むのが難しいわけ。

        自分で書いたソースコードなら暗黙に A や B を頭に思い浮かべながらソースコード(→)を読めるけど、
        他人のソースコード(→)”だけ”を渡されたら、まず A や B を → から炙り出して推測するという手間が必要となるわけ。
        その手間を軽減するためにコメントがあるわけで、または設計書や仕様書のような、とにかく A や B を炙り出ししなくても知れる手段が用意されてるのは、有用なことだと思います。

        だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。
        A と B を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード(→)の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。
        そこのバランスの問題だと思うわ。

        親コメント
      • 運用や運用支援をしている立場からの意見ですが。
        「本番環境で動かすもの」なら、設計書はほしいです。

        トラブルが発生したとき、即時の対応が必要なときに、
        すべてのプログラムソースや設定ファイルを追って「問題を関係する箇所」を探している「時間的余裕」はありません。

        設計書と事象から「問題に関係する箇所」を推定し、
        実行状況や入力データの不健全さを疑い、
        必要があれば「コードのバグ」を疑い、その箇所のプログラムソースを確認します。

        コードのバグとして扱うのは、一番最後ですが、
        設計書がないなら「本番で不具合を起こした」ことから、
        「設計ミス」や「現実に則した動作をしないもの(バグを内包)」
        として、コードの納入元に即時の調査対応を求めることをエンドユーザーから求められます。

        「コードを追う」までは、運用の契約に含まれていないことが多いのです。

        運用や運用支援をしている身からすると、大変面倒だし、回復まで時間がかかるので、
        「本番環境で動かすもの」なら設計書をつけてほしいです。

        親コメント
    • by Anonymous Coward on 2015年03月03日 22時47分 (#2771257)

      >もっと上流の業務寄りな文書って必要だと思う。

      これだな。
      ソース読めば詳細はわかるけど、全体が見えない(見えるまで時間がかかる)
      全体像、設計思想、設計の意図、データフロー、業務フロー、入出力設計書、データ定義書ぐらいは必要。
      逆に、下流の「プログラム設計書」とか、正直いらんと思う。

      #ソースコードとプログラム設計書(ソースコードと1対1に対応)渡されて、引き継ぎ終わり言われてもねぇ・・・

      親コメント
  • ソフトウェアライフサイクルプロセス [kikakurui.com]とか、
    IEC 62304/FDA ソフトウェアガイダンス/ISO 14971等のソフトウェアとリスクマネジメントがかかわるものを勉強した方がいいかと。

    そして勉強してなお不必要と考えるのなら、貴方が関わっているのはそういうものが
    不必要なソフトウェアであり、そういう領域でのみ仕事をすべき。

    #そうはいっても、このような規格に基づくソフトウェア開発は難しい。。

  • by manmos (29892) on 2015年03月03日 15時14分 (#2770909) 日記

    ソース自体が設計書(の一部)なんですが。
    大体、他の物作りでも、自然言語だけでは正確な指示は出来ないので、その仲介として図面などが存在して、それらはとてもじゃないけど、シロート(あえてカタカナ)には書くことどころか、読み取ることも出来ない。(ソースよりは判ったふりはしやすい)

    要するに、「セッケーショがぁ」と騒ぐ上司は、他の物作りの場面で図面とか判ったふりをする奴。ポンチ絵でも描いてわたしゃ納得しますって。

    • by Anonymous Coward

      社内SEなんで自分も設計書なんて作ったことなかったんですが、こないだ初めてお客さんに納品するツールを作んないといけなくなって、その「納品」のために設計書を書かされました。納品物としての設計書を。

      ほんと、ソース見ろって言いたかったです。でも見せたところでお客さんが理解できるわけないし、社内で共有する人だっていないし、作る前から作る意味がないことがわかってたのに結局その更新とかに時間がとられて非常に腹立たしかったですね……。

      • by Anonymous Coward on 2015年03月03日 15時32分 (#2770924)

        そういう単なるエビデンスとしての設計書を求められるような場合は、
        Doxygen とかの自動化ツールでババーッと作っちゃうのがいいですね。

        だいたいある程度のボリュームの文書が存在することが重要であって、
        中身なんて結局まともに読まれないことの方が多いし。

        親コメント
    • Re: (スコア:0, 興味深い)

      by Anonymous Coward

      >ソース自体が設計書(の一部)なんですが。

      こういうこという奴は「私はバカです」
      って言ってるのと同じだと思ってる。

      要求書とそれを実現する実装方法を抽象化した「設計書」がない限り「実装のミス」はわかりません。

      ある値 a と b を合計する値を求めるのが要求と仕様だったとして、
      実装が a - b になっていた場合、「ソースだけ見ても実装のミスとわかる人はいない。」

      ソースを設計書というなら「a - b」が正となり、それしか資料がなくなるのだから。

      • by manmos (29892) on 2015年03月03日 18時31分 (#2771069) 日記

        それは「よ、う、き、ゅ、う、し、よ、う、し、ょ」
        例えば、車は「エンジンが付いてて、タイヤがあって、流線型で」とか。当然そんなものでは、いきなり物が作れるはずがない。

        「自然言語」は「設計書」として不完全なツールに過ぎない。

        もちろん要求仕様書は非常に重要で、ある状況に対して最終的な結果はすべてそこにあるので、首っ引きで参照しながらソースを書きます。しかし、それは設計書ではない。

        設計書は作る側に渡すもので、提供される側が必要とすべきものではない。(その次に別の製作者に渡すために、保管ということでは必要だが)

        図面だとそれが理解出きるのに、ソフトウエアだとなぜ理解されないんだろう。

        親コメント
      • by Anonymous Coward

        あなたの理屈で必要なのは要求仕様書であって、設計書ではない。
        そして要求仕様書は設計者が書くものじゃない。

        • by Anonymous Coward

          要求仕様書なんて

          「なにがしたい」(ものを買いたい、売りたい。)

          レベルで「実現方法(機能仕様、機能設計)」はないでしょうが。

          必要なのは「機能と実装の設計」

          「コーディング仕様書なんていらない」のは同意できますが「機能実現の為の実装設計書」は必要です。

          「どういうDBでどのテーブルはどういう意味を持ち、どのフィールドは何のためで、
          どういう計算で入るべきか。」

          それが「要求仕様書?あほか」

          上記がない限り実装でミスってもけっしてわかりません。

          • by Anonymous Coward

            >「機能実現の為の実装設計書」は必要です。

            >「どういうDBでどのテーブルはどういう意味を持ち、どのフィールドは何のためで、
            >どういう計算で入るべきか。」

            機能を上から下まできっちり詰めることができるのなら、それは即ちそのまま
            ソースコードに落とし込めるということで、それなら最初からソースコードに
            そういうことを書けばいい。

            そういう意味で『ソースコードは設計書』なんです。

            # それにね、だいたい同じ頭で「機能実現の為の実装設計書」と「ソースコード」を
            # 書いたところで、両方に同じ間違いをするのが関の山でしょ。

            • by Anonymous Coward

              フィールドを計算する関数ごとに「テーブルの意味」「関連する別のフィールド」「別のテーブルの意味」
              すべてかくんですか?

              そもそもシステム全体でDBを複数使用している場合、
              「システム全体では使用してもそのクラスでは使用しない
              が値としては関連してくる」

              とかいくらでもあるわけで。

              # それにね、だいたい同じ頭で「機能実現の為の実装設計書」と「ソースコード」を
              # 書いたところで、両方に同じ間違いをするのが関の山でしょ。

              だからこそ
              「コーディング設計書」でなくて「なにをしたいか、何をするべきか、システム全体の中で何を担って、
              なにを行って、返す値は何で、システム全体でどういう意味を持つか」

              の「設計書」が必要なんですよ。
              後で他の人間がみて、「ここでバカやってる」ってわかるように。

              そもそも「何を求められていたか、そこで何するべきだったか」

              がわからなくてどうやって「やっていることのミス見つけるの?」

              • by Anonymous Coward on 2015年03月03日 19時13分 (#2771086)

                ソースコードと一対一で対応しているドキュメントじゃカバーできない、
                全体を俯瞰する情報のために設計書が必要なんですよ。

                親コメント
            • by Anonymous Coward

              まさにこれ。
              > ある値 a と b を合計する値を求めるのが要求と仕様だったとして、
              > 実装が a - b になっていた場合、「ソースだけ見ても実装のミスとわかる人はいない。」
              って言ってるけど、そもそも設計書の段階で間違われてたらどうすんだと。
              更にソースでは要求仕様をきちんと満たしてたりすると、余計に混乱するわけです。
              プログラミングでは、重複を避けろと言われますが、同じ内容を別の言語で重複して書くのは愚行です。
              *BSD や Linux にすら設計書がないのに、明らかにそれら以下の規模や複雑さのソフトに設計書が必要である明確な根拠があるとは思えないです。

      • by Anonymous Coward

        ソースには本当に「a - b」しか書いてないと思ってんの?

        まともなソースなら、どのようなことが要求されているのかは変数/関数名や
        コメントからある程度分かるように書くから、少なくとも要求仕様と実装の
        どちらかがおかしいということぐらいはほとんどの場合分かるよ。

  • この手の議論は昔からあるが、設計書になにをどう記載すべきかの統一的な基準がない。
    基本設計書、概要設計書、外部設計書など同じレイヤのドキュメントの呼び名すら統一されていない。

    プログラムとはプログラミング言語で表現された数式である。
    ドキュメントとして数式を自然言語で表現する必要性は本質的にはない。
    なぜなら自然言語には解釈の余地が存在するので、厳密に数式へ変換することは困難だからだ。
    ドキュメントに厳密さや正確さを求めるのは、不完全性定理への挑戦にも似ている気がする。

    しかし現実にはドキュメントは必要だ。
    IT業界には数式で思考できないダメなプログラマや、そもそもプログラムの書けないエスイーまで、
    本来そこにいるべきでない多くの人と協調して働く必要がある。
    注文主であるエンドユーザも技術には無縁であることが多い。
    これらの関係者を納得させ、プロジェクトを回していくためにドキュメントが役立つのだ。
    たいていのIT屋やプロジェクトでは、良くてもこのレベルでしかドキュメントを使用していない。
    そういうわけでドキュメントは、必要を満たす程度のものを最小限の手間で作成することが重要である。

    タレコミ主がもっと大きなプロジェクトを統括する立場になれば、要件定義から試験までを紐づけることで、
    機能や試験の網羅性を(ある程度)担保できるようになるだろう。
    本来、ドキュメントはこうした使い方をすべきである。
    そのためには各レベルのドキュメントの定義と一貫性を担保し、マネジメントしていく必要があるが、
    残念ながらマジメにこれに取り組んでいるところを私は知らない。
    私自身もそこまでできていない。せめてプロジェクトに文書管理担当をおければ…

  • by ymasa (31598) on 2015年03月03日 23時54分 (#2771314) 日記

    小さな仕事しかしていない人ばっかってことですね。

  • このライブラリは自由に使っていただいて構いません。
    ただしライブラリのドキュメントはありませんので、
    各自ソースを読んで使い方を勉強してください。

    こんなライブラリを積極的に使いたいと思いますか?

  • ソースコード=設計書、という意味では、ソースコード以外にソースコードと
    同じ内容の設計書を作る必要は全くない。
    (但し、ソースコードには設計時に必要な情報等コメントをきっちり書くこと。)

    より広くドキュメントという捉え方で考えると、ユーザー向けのマニュアル等、
    他に必要なドキュメントが出てくる。

    どのような役割/立場の人向けに書くのか、その役割/立場の人向けには
    どのような情報をどのような切り口でまとめるのが良いかを考えるのが大事。

  • by Anonymous Coward on 2015年03月03日 18時11分 (#2771056)

    コラム主の言うとおり、素人が書いた劣悪なドキュメントなんて「作る・管理する・見る」とあらゆる場面で無駄しか産まない。
    良質なドキュメントを作るにも手間がかかるのだから、その価値が手間を下回るなら作らないという選択もありえるでしょう。

  • by Anonymous Coward on 2015年03月03日 21時44分 (#2771206)

    最低限、どういう設計思想でどのように作られているのかは残しておきますね。引き継ぐ人のための注意事項とかちょっとした機能拡張のHowToとかも時間があれば。そうじゃないと、せっかく綺麗にモジュール分けしても、一年間プロジェクトを離れて戻ってきたら設計思想無視した無茶苦茶な改造されてることを何度も経験してますから。
    あと、設計ってプログラミングで一番苦労するところなんだから、自分がどう解決したかを誰かに説明したい。

  • 1. ソースコードがそれ即ちドキュメントだから設計書なんて不要
            ・コードを書くのが業務の大部分であるためメンテナンスに思いの至らないエンジニア
            ・コードが書ける自分は優秀だと思い込んでいるエンジニア

    2. ソースコード以外にもドキュメント(仕様書、設計書、サポート向けの資料など)は必要
            ・1の人が作った独りよがりのシステムのメンテナンス(尻拭い)をさせられているエンジニア

    3. 客や上司は何も分からないんだから適当なものを書いておけば良い
            ・自らの責務を果たせない無能なエンジニア

    ということですかね。

  • 仕様が明文化してなかったらテスト項目立てられない気がするんだが、勘でテスト項目決めてるの?
    仕様書って各レベルのテスト項目を人間が読み易くしたものと思って作れば良いものが出来るじゃないか?

    うちは中小企業相手に臨機応変に安くソフト提供してるから超簡略版しか作らないけどまったくナシではやらないな。
  • by Anonymous Coward on 2015年03月03日 15時40分 (#2770928)

    何か矛盾してないかとか、考慮忘れないかとか、確認するために。
    いったんそれがソースコードに落ちた後は、設計図は不要だと思う。

    ただ、ソースコードと対比してみるための何らかのドキュメントはあった方が良いし、それらは図を豊富にしてソースコードとは別の切り口で説明する方が良い。
    それを設計図と呼ぶのはどうかと思うが。

  • by Anonymous Coward on 2015年03月03日 15時55分 (#2770941)

    設計書無しでどこまで今の仕事ができるか考えていくとちょっと面白かった。時間、空間、役割を跨いで複数人で作業を行う際のコミュニケーションコストを最小化させるドキュメンテーションとは…って原点に立ち返った気分

  • by Anonymous Coward on 2015年03月03日 16時03分 (#2770949)

    私の場合、図や数式を用いる設計書などは、問題となることが少ない気がしますが
    日本語でゴテゴテ記述するような場合、
    設計書・仕様書が正しいかどうかあとで見ると不安になります。
    (私は、日本語で正確に記述する能力がありません。)

    うちは人的リソース不足でできませんが
    実装(ソースなど)と設計書・仕様書を別々の人間が作成し
    さらに実装と設計書・仕様書をチェックする人間を第三者が行う必要がありますか?

  • by Anonymous Coward on 2015年03月03日 16時10分 (#2770954)

    設計で金とるんだから設計書は必要。
    テストもするんだから設計書は必要。

    設計もテストもしないのかな?

    あとたれ込み人は
    設計書を書くのが下手なだけでは?

  • by Anonymous Coward on 2015年03月03日 16時14分 (#2770959)

    底辺SI勤務で、営業から「設計書の無いプロジェクトで人が足らん案件なんだけど、行ってくれる?」
    とか言われたら、絶対行きたくないですもん。

    #まぁ行かされるんだけど

typodupeerror

犯人は巨人ファンでA型で眼鏡をかけている -- あるハッカー

読み込み中...