プログラム設計は何を書くべき？

復職してこんな初歩的かつ深淵な問題にぶち当たるとは思わなかった。

プログラムを書く前に、「こうすれば実現できるんじゃない？」ということを考える「設計」というフェーズがある。*1

この設計を明文化することで、発注主や実装を担当するプログラマ、将来的に運用をしていく現場の運用担当、修正を請け負う可哀想な誰かさん(大抵自分にブーメランする）と、「プログラムの動く世界観」を共有することができ、
想定外の使い方や、ゴミツール化、的外れなデバグや修正を防げる（と、私は考えている。）

人の思考はそれぞれだから、仕様書も千差万別。
SIerによってフォーマットも違うし、そもそも、書いた人や発注主の担当者によっても書き方が違う。
場合によっては、「このフェーズでは何をすべきで、つぎ何に進むか」という、フェーズに対する認識がズレてる。

設計書の非常識1.設計書には詳細な実装方法を書く - Sacrificed & Exploited
↑2009年のこの方のエントリが、私には真実と思えるのだが、どうだろう？

前任者から見せてもらった仕様書がまさにこんな感じで、
「どう実装されているか」はプログラム1行ごとに書いてあるけど、
「なぜそういう実装になっているか」は、清々しいほど書いていない。
FxxK!

動きはプログラムを読めば分かる。
実装まで書いたら、プログラムの実装と設計書の修正で、ダブルで首が締まるじゃない。
（今まさにそれ）
動作環境やデータ構造、あるいは起動タイミングや肝となる処理の考え方など、そういう「プログラムの外」や「外から見たプログラムの動作」をまずは書くんじゃない？

コードの詳細を書き出すのは、Javadoc（自動作成ツール）に任せて、人間には人間にしかできないことをやりましょうよ……

*1:更にその前に「で、何に困ってるの？どうなれば満足なの？」を未来のユーザーから聞き出す「要件定義」というものがある。