ソースコードから運用上必要なドキュメントを自動生成・更新したい

Question

Javaのソースコードから以下のドキュメントを自動生成するようなツールやコマンド・やり方など何かないでしょうか？
あるいはGitの変更履歴などからドキュメントを自動更新するような物でも構いません．

• SRS(ソフトウェア要求仕様書)
• 非機能要件定義書
• サーバー設計書
• ネットワーク設計書

私は正直なところ，そんなものはないと思っています．
理由は，生成したいものは比較的上流の物である一方で，ソースコードは最終成果物で最下流のものであるため，遡るには遠すぎると思うからです．
この点に関して何かご意見ございましたら是非伺いたく存じます．

【2021/01/18 追記】
対象となるのは新規ではなく既存のプロジェクトです。
私が対象としているプロジェクトでは、変更があってもドキュメントの更新をせず、直接ソースコードを書き換えているような状況です。
逆に言えばソースコードは最新であることが保証されているため上記のようなものを探しておりました。

私自身そのような都合の良いものはないと考えていますが、
どうしても「そうだとして、なぜできないのか？」を知りたいのです。

漠然とした質問ですし、そもそもteratailにそぐわないものであることは百も承知ですが、
お力添えいただければ幸いです。

Answer 1

挙げられているドキュメント単位に何故ソースコードから自動生成出来ないかの説明が
無かったので、その点について回答します。

■SRS(ソフトウェア要求仕様書)
⇒エンドユーザからの現要求、つまりシステム開発をする目的を記載する仕様書なので、
ソースコードから起こすことは不可能です。
要求仕様書とは？

■非機能要件定義書
⇒非機能要件はほとんどソースコードレベルとは直接関連しない要件なので、
こちらも不可能です。
非機能要件がどのようなものがあるのか非機能要件の定義を参照して下さい。

■サーバー設計書
⇒サーバー設計書という名称から以下のような設計書と読み替えました。
これらもソースコードから読み取ることが出来ない情報が多い為、
こちらも不可能です。
ハードウェア構成図
ソフトウェア構成図
パラメータシート
etc

■ネットワーク設計書
⇒システムの規模にもよりますがソースコードからシステム全体のネットワーク構成を
逆引きすることは出来ない為、こちらも不可能です。

Comments

[odds0128]

個別に自動生成・更新できない理由を教えてくださってありがとうございます！
まさしく私が知りたかったことです。
どれも非常に納得できる理由でしたのでベストアンサーとさせていただきます。

また、参考資料も共有してくださりありがとうございます。
ウォーターフォールの開発について自分の無知を思い知らされたので、
勉強のためにぜひ読もうと思います。

重ねてお礼申し上げます。

[kaina]

参考になって何よりです。
尚、挙げられた設計書類の内容は別にウォーターフォールだから考えなければならないという
わけでは無い内容であることは頭に入れておいて下さい。

Answer 2

できてもJavaDoc生成くらい。詳細設計、機能設計レベルでしょう。
むしろコードはあくまで結果なので、そこから要件定義を探ることはできません。実際はマスタやデータも絡んでくるからです。

むしろ上流工程かたまってないのにコード書いたのですか？
それとも、設計書修正しないままコードを先にかえてしまったから整合性を取りたいとかでしょうか。

前提や背景が分かりませんが、「コードから設計書にしなければならない事態が異常」なので、そもそもの開発手法を見直すべきかと思います。

プロジェクトによって必要な設計書も違ってくるでしょうし、実装も変わってきます。

フレームワーク含めた開発標準が整備されているならまだしも、整備されているならそもそもコードから設計書なんて許される現場ではないです。

そのような仕組み、作ったところでコストに見合うものにはなりません。先に書いたようにコードから要求仕様や非機能要件を辿るのは不可能です。
辿れるような現場ならきちんとした設計書ができていてメンテナンスも的確に行われています。

Comments

[odds0128]

回答ありがとうございます。
全体を通しておっしゃる通りで何も言い返せません、、、

お恥ずかしながら一つ飲み込めておらず質問なのですが、「実際はマスタやデータも絡んでくるからです。」と言う点について、マスタやデータが絡むとどうしてコードから要件定義を探れないのでしょうか？

[m.ts10806]

要件を満たすためにマスタが使われてる場合（例えばユーザーの権限や所属グループ、組織など）、実装から要件をたどることは不可能かと思います。
どの程度実装が標準化されているかにもよりますが。

ただ、「同じ結果を出すための実装方法は1つではない」時点で、逆は無理ですよね。
自動じゃなくても、手動で目検だったとしても、やはり詳細設計時に作る機能設計書くらいまでではないでしょうか。
「なぜこの機能が必要か」「画面同士の連携」までは見えてこないと思います。

Answer 3

探しているものは、「上流工程のドキュメントを自動生成するようなツールやコマンド・やり方」ではなくて「運用上必要な管理ドキュメントを自動生成するツールやコマンド・やり方」ではないですか？

上流工程のドキュメントの役割は主に「顧客との合意形成のエビデンス」です。
システム構築後に自動生成されても意味を持ちません。

ただ、上流工程で作成したドキュメントの中には運用中にアップデートされ続けるものもあります。
パラメータシート等ですね。
この辺は、実設定から逆引きできるものもあるので、自動生成(サポート)ツールが用意されているケースがあります。

Comments

[odds0128]

ありがとうございます。
確かにおっしゃる通り、「運用上必要な管理ドキュメント」と言った方が正確でした。
質問本文に反映させていただきました！

ところで一点質問なのですが、「自動生成(サポート)ツールが"用意されている"ケースがあります」とのことですが、ということは一般に使えるようなものではなく各社で独自に作っているという解釈であっていますでしょうか？

あるいはもし一般に使えるそういうサービスをご存じでしたら教えていただきたいです。