設計書の非常識1.設計書には詳細な実装方法を書く
SIerの常識：「誰が書いても同じソースコードになるように、詳細な実装方法の記述された設計書を書かなければならない」
プログラマの常識：「誰が書いても同じソースコードになるような設計書は書くだけ無駄、誰が書いても同じ振る舞いをするように、詳細に振る舞いを記述した設計書を書かなければならない。」
プログラムを作るうえで設計書や、仕様書の類は欠かすことができない
だが、設計書や仕様書をちゃんと作っているプロジェクトでもよくデスマーチに陥っている。
なぜか？「設計書に記載するべき内容が間違っている」からだ。
（設計が間違っている場合も多々あるが。）
間違ったことをまじめにやっても良い結果は得られない。
「誰が書いても同じコード」は大事なことなのか - yvsu pron. yas
昨日、大手SIerの方々と話をする機会があって、そこで出てきたのが、「誰が書いても同じコード」になることが重要で、それを実現するために、ドキュメントをいっぱい書かなくてはいけないという話。大手SIerは、大体同じことを考えていると思います。
でも、「誰が書いても同じコード」にするってのは、そもそも無理だと思うんだよね。そうやって、わざわざドキュメントをたくさん書かせても、めためたなコードを書くやつはいて、総合テストするときに、現場は燃え上がるもの。ある程度の規模以上のプロジェクトなら、どこでもそんな感じじゃないかと思います。
プログラムするという仕事をSE(笑)に移すべきではない。SEはSEで(笑)などとつけられないように、 要件定義の本文を全うするべき。(SIerではSEとは主に要件定義を行うこととされている)
アルゴリズムの選択と実装の方法論はプログラマの裁量に任せてしまう。 SEはプログラマに仕様を提示するわけだけども、その仕様書にはアルゴリズムというかロジックについての記述はしてはいけない。 それはアルゴリズムを考える専門家であるところのプログラマに任せればよい。 その代わり、業務分析や要件定義といった部分はSEの裁量に任せられるべきだし、 それはそれで高度な技能を必要とする仕事なのだから、専門性を発揮すればよい。
自然言語でロジックを書いてはいけない
ロジックを自然言語で書くというのは、かなりナンセンスです。自然言語はロジックの記述には向きません。 プログラミング言語はそもそもがプログラムというかロジックを記述するために設計されているので、 そのロジックの記述に曖昧さが入らないよう工夫されています。
自然言語でロジックを記述してからプログラム言語に翻訳するというのは、 プログラム言語に堪能ではない人の場合には有効かもしれません。 あるいは、はるか古代、PCが貧弱で対話的なプログラミングができなかった時代なら有効だったかもしれない。
想像してみてください。
英語の通訳を雇ったら、自分の言った日本語をメモしてから英語に直して、それから現地人に語りかけたとしたならば？
一般的な感想はこうでしょう。「おまえ、それでもプロか？」
まともなプログラマならロジックを直接その言語で考えられます。 むしろ、プログラム言語のほうがロジックの記述に向いているのだから、プログラム言語で思考する方が楽だし、間違いがない。
かといってプログラマの平均的ロジック表現力は総じて低い。 自然言語で考えてから翻訳するレベルでも書けるなら駆り出さないといけないぐらいには人材不足だったりもします。
【翻訳】How to be a program manager - Joel on Software - GoTheDistance
仕様書？本気かい？それじゃ遅すぎる
仕様書が全体の流れがそれを書かないというアイデアで編成されているんじゃないかと疑いたくなるような、愚かな役人的事務処理の典型になっている開発部隊はとても多く存在する。こういう人たちは間違っている。機能仕様書を書くことはアジャイル開発のまさに肝となるものだ、なぜならあなたがコードを書く前に多くの実装できうる設計を素早くイテレートさせられるからだ。コードに比べたら、書かれた仕様書など変化を生むには取るに足らない。正しく仕様書を書くことは頭に浮かんだ設計を通じて素早く欠陥を見つけさせてくれるので、もっと多くの設計をイテレートすることが出来る。機能仕様書を持つチームはより良く設計された製品を持っている、なぜなら彼らは素早くより多くの実現可能な解決策を探索する機会を持ったからだ。また、より早くコードを書くことになる。なぜなら彼らが何が必要になるのかという所からスタートするにあたり、より明確な絵があるからだ。機能仕様書はとても重要なので、Fog Creekではほどんど辛くも早くも無いルールの１つが｢仕様がないなら、コードも無い｣である。
機能仕様書の正確な形式というのは、色々と種類があるかもしれない。機能仕様書がやらなきゃいけないことはプログラムがどうやって振舞うのかを説明することだけだ。コードが内部的にどう動くかということは一切説明されない。最も上位レベルである｢ビジョン記述書｣、1ページ以内でその新しい機能の骨子を説明するもの、から取り掛かる。ひとたびそれが明確になれば、ストーリーボードの開発ができる。そこには、アプリケーションがどういう働きをするのかを詳細に書かれたノートと共に、アプリケーションを通じてユーザーが歩む行程を示した画面のモックアップなどがある。多くの機能群、特にUIが重要な機能は、一度これらのストーリーボードがあれば、もう大丈夫だ。それがあなたの仕様書だ。今キミはJason Friedのように進むことが出来る。
隠された振る舞いにあるより複雑な機能群については、UIのストーリーボードに書くのではなくもっと詳細に書き記したくなることだろう。どんな場合においても、本当に仕様書を書くということはコードの最初の一行が書かれるずっと先立って問題・葛藤を発見し、そして課題をデザインする手助けになるので、正にコード書いている時に再実装もしくは改悪になるかもしれない準最適な設計を強いるような急に振ってくる予期しない問題がとても少ないものになるのだ。
実装方法の詳細が書かれた設計書はたいていの場合、
以下のような理由から保守の役には立たない。
