アカウント名:
パスワード:
DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。
> しかし、自動出力したドキュメントは「上司がわからないから」として却下された。
これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。
＞もっと上流の業務寄りな文書って必要だと思う。
ほんとこれ。「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」
なぜなら「何をしているか」は分かっても「何をしたいか（したかったか）」がわからないから。
極端に抽象化した話、X+Ｙ =Bしているのがわかっても、Xがなんなのか（リンゴなのか、速度なのか）、Bは何かわからなければドキュメントの意味がない。もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」
これがわからんと意味がない。逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。
たとえば状態Ａを、状態Ｂにするのが目的なアプリがあったとして、Ａ → Ｂソースコードに書かれてるのは → の具体的な方法。→ から Ａ や Ｂ を炙り出して推測しないといけないから、だから他人の書いたソースコードって読むのが難しいわけ。
自分で書いたソースコードなら暗黙に Ａ や Ｂ を頭に思い浮かべながらソースコード（→）を読めるけど、他人のソースコード（→）”だけ”を渡されたら、まず Ａ や Ｂ を → から炙り出して推測するという手間が必要となるわけ。その手間を軽減するためにコメントがあるわけで、または設計書や仕様書のような、とにかく Ａ や Ｂ を炙り出ししなくても知れる手段が用意されてるのは、有用なことだと思います。
だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。Ａ と Ｂ を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード（→）の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。そこのバランスの問題だと思うわ。
> Ａ と Ｂ を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード（→）の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。
それは書いた奴が無能なだけ駄目な仕様書の典型じゃんたまにいるよね、大昔の知識で止まってたり技術者としては並以下なのにソースコードやSQLを中途半端に書いてきて足枷ばかりはめようとするアホ
>だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。逆に、中身は邪魔です。仕様が網羅されているかを見るのに、コードに引っ張られて見てしまい、バグが有る時は作成者と同じ穴に嵌りがち。純粋に「A→B」が「何をしたいのか？」って点で表現されている物の方がずっと良い。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
物事のやり方は一つではない -- Perlな人
設計書と一言で言っても (スコア:3, 興味深い)
DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。
> しかし、自動出力したドキュメントは「上司がわからないから」として却下された。
これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。
Re: (スコア:5, すばらしい洞察)
＞もっと上流の業務寄りな文書って必要だと思う。
ほんとこれ。
「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」
なぜなら「何をしているか」は分かっても「何をしたいか（したかったか）」がわからないから。
極端に抽象化した話、
X+Ｙ =B
しているのがわかっても、Xがなんなのか（リンゴなのか、速度なのか）、Bは何かわからなければドキュメントの意味がない。
もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」
これがわからんと意味がない。
逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。
Re:設計書と一言で言っても (スコア:2)
たとえば状態Ａを、状態Ｂにするのが目的なアプリがあったとして、
Ａ → Ｂ
ソースコードに書かれてるのは → の具体的な方法。
→ から Ａ や Ｂ を炙り出して推測しないといけないから、だから他人の書いたソースコードって読むのが難しいわけ。
自分で書いたソースコードなら暗黙に Ａ や Ｂ を頭に思い浮かべながらソースコード（→）を読めるけど、
他人のソースコード（→）”だけ”を渡されたら、まず Ａ や Ｂ を → から炙り出して推測するという手間が必要となるわけ。
その手間を軽減するためにコメントがあるわけで、または設計書や仕様書のような、とにかく Ａ や Ｂ を炙り出ししなくても知れる手段が用意されてるのは、有用なことだと思います。
だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。
Ａ と Ｂ を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード（→）の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。
そこのバランスの問題だと思うわ。
Re: (スコア:0)
> Ａ と Ｂ を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード（→）の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。
それは書いた奴が無能なだけ
駄目な仕様書の典型じゃん
たまにいるよね、大昔の知識で止まってたり技術者としては並以下なのにソースコードやSQLを中途半端に書いてきて足枷ばかりはめようとするアホ
Re: (スコア:0)
>だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。
逆に、中身は邪魔です。
仕様が網羅されているかを見るのに、コードに引っ張られて見てしまい、バグが有る時は作成者と同じ穴に嵌りがち。
純粋に「A→B」が「何をしたいのか？」って点で表現されている物の方がずっと良い。