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