前置き

全体として、SIerをイメージしてます。
個人の視野を元に書いてるので「ウチはSIerだが、そんなアレじゃないぞ！」という方もいらっしゃるかと。
その場合はアレじゃない環境を維持・発展させていっていただければ幸いです。

こんなタイトルにしといてなんですが、私は詳細設計書を書きたくない派です。
もっと言うと、ロジックの和訳も書かずに済むなら書きたくないです。
書くにしたってせめて、せめてExcelじゃなくてMarkdownにして欲しい……！

とまぁ、以下は**書きたくない人から見た「書くメリット」**の話になります。

詳細設計書　とは

ここで言う詳細設計書は主に以下の要素で構成されたものを指すとします。
メソッドの仕様とかガッツリ書いてある仕様書は含みません。仕様書はロジックほとんど書いてないし。

表紙
改訂履歴
どう動いてほしいかの願望(柔軟剤たっぷりふわっと仕立て)
ロジックの和訳ほぼ全文

この詳細設計書ですが、詳細と謳う割に対象範囲が広いことが多いです。
というか、対象のModelクラスが単一責任の原則ブッチしてるものばかり見てきたため、
大量の機能がゴチャッとカクテルされたクラスのロジックべた書きだったり……

そもそも詳細設計書って要るの？

職場によると思いますが、少なくとも私の知る限りでは必要です。
……ほら、成果物として定義されるからさ。拡張子.xls指定で。
そんでもって、この記事も一応は**役に立つ(場面もある)よ！**って立場なのでね？

ロジックの和訳を書くメリット

早速ですが、そんなもんがあるのかと言うとですね、あるんです。2つほど。

プログラムが読めない人でも動作が理解できる
日本語で書けるようなコードしか製造されなくなる

1.プログラムが読めない人でも動作が理解できる

よく言われつつも、「プログラム読めないヤツが実装に関わってくる意味がない」とバッサリ切られるやつです。四天王最弱ポジです。ひねり出したはずなのに2名欠員してますが。

じゃあ、プログラム読めない人が理解できると何が嬉しいのか。
それはベテランに業務知識の観点でレビューしてもらえることです。

プログラム読めない人は「プログラミング技能ALL0のプー太郎」だけではなくて、「Javaは全く読めないが、COBOLのスペシャリストでその現場のベテラン」みたいな人も居ます。自分が持ってる案件がJavaなら、後者のベテランもプログラム読めない人になってしまいます。
この時、プー太郎はともかくとしてベテランのレビューを受ける価値はあります。
というのも、ドキュメント化されていない業務知識上の隠し仕様がそのベテランの記憶に眠っている可能性が低くないからです。〇〇社相手の場合だけ計算時の端数処理が違うとか。

仕様書作ってそれで確認してもらうと言う手もありますが、伝統的にロジック和訳な現場では仕様で聞くよりロジックで聞いたほうが思い出す確率で有利です。
「このロジック、前にやらかして大炎上したぞ」という記憶は似たようなロジック見たときのほうが思い出しやすいものです。

そして、ここで隠し仕様をクリアしないとフラグが立ちます。後々死にます。最悪、本番障害発生まで気づけません。
なんせ仕様として表に出てきてないので。テストもすんなり通過します。

2.日本語で書けるようなコードしか製造されなくなる

イテレータを使わずにカウンタでループ回したり、ポリモーフィズムが禁止されたりオーバーロードが禁止されたりするアレです。
**エンジニア視点ならただのデメリットです。**バリバリのプログラマ諸兄には最早苦痛かと思います。

ただ、担当者がプロジェクト移動などで変わった場合、新しくアサインされた次の担当者がバリバリのプログラマである保障がありません。
コード見てもわけわからんとなってキノウテイシしたりします。
一方、日本語で書けるようなコードは往々にして言語機能をろくに使わないので、まぁ大体読めます。読めればコピペ出来るのでとりあえずはしのげるのです。

現場でガッツリ言語知識を学んでいけるならこうはならないかもしれません。しかし、SIerでは言語知識は蔑ろにされやすい(業務知識が重いので。両立なんて簡単には言えない)ため、そもそも教えられる人員が居るか……
そんなわけで、現場がどうにかメンテ出来るか、という点では日本語書き下しコードの方が優位なのです。

他にも、設計だけ担当してコーディングは別の人に投げるパターンも。
ここまで来るとプログラマとは名ばかりのタイピストな気もしますが。オフショア使用率を上げるとかそういう政治的な理由でこうなることもあるので。
もし、投げ先が信用できるなら仕様書作ってそれだけ投げればいいと思います。

ロジックの和訳を書くデメリット

google先生に聞いてください。いっぱいヒットします。
詳細設計書の時点でdisられっぷりが凄まじいです。詳細設計書に親を殺された人はいないと思いますが、余暇を殺された人は居るからね。シカタナイネ。
今回はメリット謳いましたが、デメリットはこの程度じゃ書ききれないのです。余白足りません。

とはいえ、丸投げはアレなので1つ挙げます。
詳細設計書にロジック書いてると、入出力などのパターンが考慮されず、ロジック内部にバラバラに書かれる形になっていきます。
こうなると、テストの際に必要なパターンが仕様から読み取れません。稀にロジックと別にパターン一覧が載っていたりしますが、保守フェーズに入るとメンテされないとかザラですし。
結果としてテストケース自体に漏れが発生しやすくなり、検知がどんどん遅くなります。

最悪、障害対応案件でこんにちはです。

メリットは得つつ、書かない方法は？

残念ですが、一発で解決する方法は無いんじゃないですかね。少なくとも時間やお金のかからない方法は。

ただし、負荷を減らす方法ならあります。

まず、ベテランにレビューしてもらうための設計書はぶっちゃけコーディングには不要です。
ならば、設計書は一旦置いておいてさっさとコード書いてしまえば良いのです。
ユニットテストまで終わったら、その時点でコードを和訳して詳細設計書を作成。これをレビューしてもらえば完了です。
コードから設計書を自動生成するツールを作ってしまうのも手ですし。
レビューで隠し仕様が発覚しても、修正のインパクトは設計書先行の場合と変わらないでしょう。コード直して和訳すればOKです。

設計書だけ作って他人に投げるパターンでも、自分で先にコード書いちゃいましょう。
すごい無駄な気がしますし実際無駄ですが、答え合わせの気分でコードレビューできます。
あと、例外とかの細々したところは考える手間が省けるかもしれません。投げ先の技量次第ではありますが。

次に、少しずつ少しずつ、言語機能を周りに布教していきましょう。
コレをしないといつまでたっても日本語プログラミングから脱出できません。
布教相手が便利だと感じないと成功しないので気をつけましょう。

布教失敗の例として、C#でオーバーロードを布教したらgrep出来なくて不便だと。HAHAHA……