アカウント名:
パスワード:
DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。
> しかし、自動出力したドキュメントは「上司がわからないから」として却下された。
これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。
>もっと上流の業務寄りな文書って必要だと思う。
ほんとこれ。「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」
なぜなら「何をしているか」は分かっても「何をしたいか(したかったか)」がわからないから。
極端に抽象化した話、X+Y =Bしているのがわかっても、Xがなんなのか(リンゴなのか、速度なのか)、Bは何かわからなければドキュメントの意味がない。もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」
これがわからんと意味がない。逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。
ドキュメントが作られていても、「何をしたいか(したかったか)」が分からなければ意味は無いですよね。逆にコメントやソースや自動作成ドキュメントであっても、「何をしたいか(したかったか)」が判るようになっていれば問題無いですよね。正確には「コメントや自動作成ドキュメントなんてやくに立たない」ではなく「(ドキュメント作成能力にない人間による)ドキュメントやコメントや自動作成ドキュメントなんてやくに立たない」ではないでしょうか。自動生成で「何をしたいか(したかったか)」が出力されるよう書かれたソースなら全て解決。
「何をしたいか(したかったか)」
これは理論的にコメントや自動作成ドキュメントからは本質的に作成不可能なんですよ。
なぜか。
何かバグがあったとします。「何をしたいか、したかったか(要求、仕様、設計)」と「何をしているか(ソースコード)」が乖離しているからバグがあるわけです。結局出来上がるものは本来の「何がしたかったか」はわからないのです。
なので、自動作成ドキュメントでできたもの(だけ)なんて、メンテ時には役に立たないんですよ。ほとんどの場合。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
Stableって古いって意味だっけ? -- Debian初級
設計書と一言で言っても (スコア:3, 興味深い)
DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。
> しかし、自動出力したドキュメントは「上司がわからないから」として却下された。
これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。
Re: (スコア:5, すばらしい洞察)
>もっと上流の業務寄りな文書って必要だと思う。
ほんとこれ。
「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」
なぜなら「何をしているか」は分かっても「何をしたいか(したかったか)」がわからないから。
極端に抽象化した話、
X+Y =B
しているのがわかっても、Xがなんなのか(リンゴなのか、速度なのか)、Bは何かわからなければドキュメントの意味がない。
もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」
これがわからんと意味がない。
逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。
Re:設計書と一言で言っても (スコア:0)
ドキュメントが作られていても、「何をしたいか(したかったか)」が分からなければ意味は無いですよね。
逆にコメントやソースや自動作成ドキュメントであっても、「何をしたいか(したかったか)」が判るようになっていれば問題無いですよね。
正確には「コメントや自動作成ドキュメントなんてやくに立たない」ではなく
「(ドキュメント作成能力にない人間による)ドキュメントやコメントや自動作成ドキュメントなんてやくに立たない」
ではないでしょうか。自動生成で「何をしたいか(したかったか)」が出力されるよう書かれたソースなら全て解決。
Re: (スコア:0)
「何をしたいか(したかったか)」
これは理論的にコメントや自動作成ドキュメントからは本質的に作成不可能なんですよ。
なぜか。
何かバグがあったとします。
「何をしたいか、したかったか(要求、仕様、設計)」と「何をしているか(ソースコード)」が乖離しているからバグがあるわけです。結局出来上がるものは本来の「何がしたかったか」はわからないのです。
なので、自動作成ドキュメントでできたもの(だけ)なんて、メンテ時には役に立たないんですよ。ほとんどの場合。