アカウント名:
パスワード:
DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。
> しかし、自動出力したドキュメントは「上司がわからないから」として却下された。
これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。
＞もっと上流の業務寄りな文書って必要だと思う。
ほんとこれ。「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」
なぜなら「何をしているか」は分かっても「何をしたいか（したかったか）」がわからないから。
極端に抽象化した話、X+Ｙ =Bしているのがわかっても、Xがなんなのか（リンゴなのか、速度なのか）、Bは何かわからなければドキュメントの意味がない。もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」
これがわからんと意味がない。逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。
運用や運用支援をしている立場からの意見ですが。「本番環境で動かすもの」なら、設計書はほしいです。
トラブルが発生したとき、即時の対応が必要なときに、すべてのプログラムソースや設定ファイルを追って「問題を関係する箇所」を探している「時間的余裕」はありません。
設計書と事象から「問題に関係する箇所」を推定し、実行状況や入力データの不健全さを疑い、必要があれば「コードのバグ」を疑い、その箇所のプログラムソースを確認します。
コードのバグとして扱うのは、一番最後ですが、設計書がないなら「本番で不具合を起こした」ことから、「設計ミス」や「現実に則した動作をしないもの(バグを内包)」として、コードの納入元に即時の調査対応を求めることをエンドユーザーから求められます。
「コードを追う」までは、運用の契約に含まれていないことが多いのです。
運用や運用支援をしている身からすると、大変面倒だし、回復まで時間がかかるので、「本番環境で動かすもの」なら設計書をつけてほしいです。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
ソースを見ろ -- ある4桁UID
設計書と一言で言っても (スコア:3, 興味深い)
DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。
> しかし、自動出力したドキュメントは「上司がわからないから」として却下された。
これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。
Re: (スコア:5, すばらしい洞察)
＞もっと上流の業務寄りな文書って必要だと思う。
ほんとこれ。
「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」
なぜなら「何をしているか」は分かっても「何をしたいか（したかったか）」がわからないから。
極端に抽象化した話、
X+Ｙ =B
しているのがわかっても、Xがなんなのか（リンゴなのか、速度なのか）、Bは何かわからなければドキュメントの意味がない。
もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」
これがわからんと意味がない。
逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。
運用や運用支援の立場から (スコア:2)
運用や運用支援をしている立場からの意見ですが。
「本番環境で動かすもの」なら、設計書はほしいです。
トラブルが発生したとき、即時の対応が必要なときに、
すべてのプログラムソースや設定ファイルを追って「問題を関係する箇所」を探している「時間的余裕」はありません。
設計書と事象から「問題に関係する箇所」を推定し、
実行状況や入力データの不健全さを疑い、
必要があれば「コードのバグ」を疑い、その箇所のプログラムソースを確認します。
コードのバグとして扱うのは、一番最後ですが、
設計書がないなら「本番で不具合を起こした」ことから、
「設計ミス」や「現実に則した動作をしないもの(バグを内包)」
として、コードの納入元に即時の調査対応を求めることをエンドユーザーから求められます。
「コードを追う」までは、運用の契約に含まれていないことが多いのです。
運用や運用支援をしている身からすると、大変面倒だし、回復まで時間がかかるので、
「本番環境で動かすもの」なら設計書をつけてほしいです。