仕様書、設計書について

1 ：11/11/26 〜 最終レス ：11/12/09

外部だの内部だの基本だの詳細だの…
曖昧な基準で書かれた、いろいろな名前で呼ばれてて
「これってどうなの？」「意味あるの？」といった物に出くわす事も少なくない
しかし、純粋にプログラミングだけをして食べていくことは、昨今じゃ難しく
避けて通れない、否が応でも作る機会に出くわしてしまう、そんなドキュメントたち
設計書や仕様書についても、マ視点で語ろうぜ
・自分のなかでの仕様書/設計書の呼び方と分け方
・成功談、失敗談
・仕様書/設計書は何を使って作成する？(Word/Excel/HTML/手書き！)
・仕様書/設計書に含める図の作成方法や使っているツール紹介
・炎上プロジェクトでみた(よくない意味で)素晴らしい仕様書/設計書
・そもそも仕様書/設計書って本当に必要なの？
・こんな仕様書/設計書は、ぶっちゃけアリ？ナシ？
などなど、設計書にまつわる話題を募集

2 ：

関連スレ
【その２】Excelで仕様書を作る会社の奴の数→
http://hibari.2ch.net/test/read.cgi/prog/1177362668/
DBAがテーブルの仕様の説明資料作らんのだが
http://hibari.2ch.net/test/read.cgi/prog/1318690907/
仕様書の書き方
http://hibari.2ch.net/test/read.cgi/prog/1191806449/
仕様書とか意味あるの？
http://hibari.2ch.net/test/read.cgi/prog/1267241758/
(´･ω･｀)仕様書ぶちす！
http://hibari.2ch.net/test/read.cgi/prog/1195826467/
設計書を作ってるせいで生産性落ちてないか？
http://hibari.2ch.net/test/read.cgi/prog/1169735232/
詳細設計をしても逆にコーディングしにくくなるだけ
http://hibari.2ch.net/test/read.cgi/prog/1280647235/

3 ：

投げっぱなしもあれなので
・俺の中の定義
外部設計==基本設計、内部設計==詳細設計
プログラム設計はソースコードで代用できるため不要
外部設計/基本設計
　UIやエンドユーザーが意識するレベルでのI/O、やりたい事などを纏めた資料
　理由があって意図的に制限する場合を除いて、実装方針の変更には影響のしないレベルの情報
内部設計/詳細設計
　入出力の詳細や分岐条件、メッセージ、処理順序など並べた
　フローチャートのような分岐やループなど、コーディング上で表現する方法が複数あるような
　意味のない情報は「明記してはいけない」
プログラム設計
　2重管理になるだけで無駄なので、ソースコードが全て
　javadocやXMLドキュメントコメント、コード内のコメントなど、コードでは表現できない情報
　クラス図などコードより抽出できる情報

4 ：

・実際の運用
外部設計/基本設計、内部設計/詳細設計
　箇条書きの要件定義、またはループや分岐を書いたフローチャート
　外部/基本設計が詳しい場合、内部/詳細は内容のコピペか焼き直し
　内部/詳細の修正でも必ず外部/基本設計が修正される
プログラム設計
　そんなの作ってる余裕なんてないです＞＜；
　コピペが何割かを占めるコードだけが絶対でありそれコメント(そもそもない)含めて他は不要
---
正直マ暦はあんまり長くはないのだけれど、これって普通のことなのかな…？

5 ：

ちなみに作るのに使うのは基本的にExcelです。
もちろん方眼紙です。
図はオブジェクトたち。
たまーにWordもありますが、終盤はファイルがいくつか見事にぶち壊されてます。
レビュアーが意図してる「仕様書」が何かを察することが、うまくやるコツなのかなって
最近思うようになってきました。書きたくない、じゃ通らないですし…。

6 ：

ソースコードは設計書だと考えるべし。
設計はなるべくコードとして書くべし。
コードから自動生成できるたぐいの情報は、
別にドキュメントにまとめる必要はない。
仕様書はソースコードにコメントとして書くべし。
またはテストとして書くべし。
Excel、他形式のドキュメントはたたき台としての意味はあるが、
最終的にはソースコードに全て記述するべし。
別の形式として見たければ、ソースコードから変換すべし。

7 ：

ケースバイケース
以上終了

8 ：

結局ある程度の実装経験がないと設計なんて出来ないよ
でも、設計から入れ実装は後だっていう微妙な風潮
しかも、つくる設計書の記述内容は、実装前に作るものとしてはイマイチな内容

9 ：

設計書とプログラムが食い違っていないか、機械的に検証する手段がないから、どんなに頑張って設計書作っても立派なプログラムが出来るわけじゃない。
結局設計書作るのって自己満足でしかないよね。

10 ：

設計書作ること自体が目的になるとページ数だけ多くなって誰も読まなくなるな
そして設計書があるのにまったく見ずにソース見ながら電話対応するようになる

11 ：

ソース見て判断できない人が見てるフリするための資料になってることが多いな

12 ：

大手だと品質保証のためとか言ってコーディング前に設計書を要求されるけど、
誰もまともにレビューしてなくて結局実コードのテストで
設計段階の間違いがボロボロ発見されるような現場ばかり。

13 ：

設計書なんて大枠だけきっちりしてればいいんだよ
あとインターフェイス部分とエラー処理と

14 ：

現状のドキュメントはバッチ処理にはソコソコ役に立つけど
オンラインだと矛盾が多い
新しい設計書の技法出来ないかな？
UMLに拡充する形でいいけど
あと、各社マチマチな工程名称も統一して情報処理試験でキッチリ記述と読み取りを出して欲しい
納品の為にしか存在価値のないものがおおすぎる

15 ：

>>12 想像力があっても実物の挙動は予想不可能なんだぜﾋｧｯﾊｰ

16 ：

文章での説明にしても図説（もちろんフローチャート()）にしても
例外をうまいこと表現できないから、なんか書いてて、ウアーってなる
他のとこだけコードよりの内容が要求されるのにｗｗ
でも他の人みると、そもそも例外なんてアウトオブ思考だったわ

17 ：

>>14
確かに、設計まわりの明確な名称はあるとかなり嬉しいな
とにかく何もかもが曖昧すぎるんだよな

18 ：

>>12
レビューしないだけマシだわ
設計書段階で馬鹿みたいレビュー繰り返してる内に
フローチャートを作ってた事あったし
挙げ句に設計書レビューに無駄に時間がかかった結果
実装はデスマーチになってるから本末転倒の極み

19 ：

設計段階で何するかは煮詰めたほうがいいよ。
実装者がアイディアマンになってしまうのは良くない。
俺が実装して痛い目見た経験から。

20 ：

>>19
詰めるべきは客先交えて決める外部仕様だろ
設計で内部ロジックなんか詰めてもしょうがねーよ

21 ：

DB設計と画面のモック作るだけ。

22 ：

マなんて信用してないから書かせる

23 ：

マはマで設計が信用ならないって言ってたりするからな
どっちであっても、出来る奴と出来ない奴の差が激しすぎるんだよな
なまじ形だけなら誰でも出来るもんだから、ひどい物でもなんとかなってしまうっていう

24 ：

つか、システム全体の設計はともかく詳細設計書はコード書く本人に書かせてレビューするだろ。
新人とかなら詳細設計書まで書いてやって渡すこともあるけど。

25 ：

>>24
新人じゃないならそれこそ実装したコードレビューした方が早いだろ

26 ：

こういうのみると、つくづく設計関連の用語の意味が統一されてないのが
諸悪の根源だって気がしてくるわ

27 ：

>>26
諸悪の根源は別のところにあります
本質を見抜く目を養わないと一緒ドカタですよ？

28 ：

建築業界って、大工が「俺の作ったもんが設計書だ！」って思う人いるんだろうか

29 ：

この前ブックオフで「仕様書の書き方」みたいな本があったんだけど、結局サンプルはオマケ程度で中身スカスカだった。
ちなみに俺が超参考になったのは、某大手の社員用サイトにある雛形だった。
しかしそれを下請に見せない理由がよく分からん。
その形式で納品すればそこそこな品質になるはずだが、社外秘なんだよ

30 ：

基本的にそこらの書店にあるような仕様書サンプルってプログラム素人向け、顧客が理解できる程度のものだからね。

31 ：

この業界自体土方だけどな
土方根性土方思想がはびこりすぎて個人でどうにかできる状況じゃねーよ(´･ω･｀)はあまじああ

32 ：

>>28
モジュールを指して設計書という奴は居ないだろう
ソースに該当するのはなんだろうな

33 ：

>>28
大工が建築物にコメント書くのが許されるんなら設計書にならなくもない
物置程度ならそれで充分なんじゃないかな、よくわからんけど

34 ：

>>33
建材に印ついてたりはするよな

35 ：11/12/09

うちのポストにもたまに印がついてる