パスワードを忘れた? アカウント作成
この議論は賞味期限が切れたので、アーカイブ化されています。 新たにコメントを付けることはできません。

スラッシュドットに聞け:ソフトウェア開発の現場で設計書は必須か」記事へのコメント

  • DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。

    > しかし、自動出力したドキュメントは「上司がわからないから」として却下された。

    これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。

    • by Anonymous Coward on 2015年03月03日 15時30分 (#2770923)

      >もっと上流の業務寄りな文書って必要だと思う。

      ほんとこれ。
      「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」

      なぜなら「何をしているか」は分かっても「何をしたいか(したかったか)」がわからないから。

      極端に抽象化した話、
      X+Y =B
      しているのがわかっても、Xがなんなのか(リンゴなのか、速度なのか)、Bは何かわからなければドキュメントの意味がない。
      もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」

      これがわからんと意味がない。
      逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。

      親コメント
      • たとえば状態Aを、状態Bにするのが目的なアプリがあったとして、
        A → B
        ソースコードに書かれてるのは → の具体的な方法。
        → から A や B を炙り出して推測しないといけないから、だから他人の書いたソースコードって読むのが難しいわけ。

        自分で書いたソースコードなら暗黙に A や B を頭に思い浮かべながらソースコード(→)を読めるけど、
        他人のソースコード(→)”だけ”を渡されたら、まず A や B を → から炙り出して推測するという手間が必要となるわけ。
        その手間を軽減するためにコメントがあるわけで、または設計書や仕様書のような、とにかく A や B を炙り出ししなくても知れる手段が用意されてるのは、有用なことだと思います。

        だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。
        A と B を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード(→)の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。
        そこのバランスの問題だと思うわ。

        親コメント
        • by Anonymous Coward

          > A と B を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード(→)の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。

          それは書いた奴が無能なだけ
          駄目な仕様書の典型じゃん
          たまにいるよね、大昔の知識で止まってたり技術者としては並以下なのにソースコードやSQLを中途半端に書いてきて足枷ばかりはめようとするアホ

        • by Anonymous Coward

          >だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。
          逆に、中身は邪魔です。
          仕様が網羅されているかを見るのに、コードに引っ張られて見てしまい、バグが有る時は作成者と同じ穴に嵌りがち。
          純粋に「A→B」が「何をしたいのか?」って点で表現されている物の方がずっと良い。

      • 運用や運用支援をしている立場からの意見ですが。
        「本番環境で動かすもの」なら、設計書はほしいです。

        トラブルが発生したとき、即時の対応が必要なときに、
        すべてのプログラムソースや設定ファイルを追って「問題を関係する箇所」を探している「時間的余裕」はありません。

        設計書と事象から「問題に関係する箇所」を推定し、
        実行状況や入力データの不健全さを疑い、
        必要があれば「コードのバグ」を疑い、その箇所のプログラムソースを確認します。

        コードのバグとして扱うのは、一番最後ですが、
        設計書がないなら「本番で不具合を起こした」ことから、
        「設計ミス」や「現実に則した動作をしないもの(バグを内包)」
        として、コードの納入元に即時の調査対応を求めることをエンドユーザーから求められます。

        「コードを追う」までは、運用の契約に含まれていないことが多いのです。

        運用や運用支援をしている身からすると、大変面倒だし、回復まで時間がかかるので、
        「本番環境で動かすもの」なら設計書をつけてほしいです。

        親コメント
      • by Anonymous Coward

        ドキュメントが作られていても、「何をしたいか(したかったか)」が分からなければ意味は無いですよね。
        逆にコメントやソースや自動作成ドキュメントであっても、「何をしたいか(したかったか)」が判るようになっていれば問題無いですよね。
        正確には「コメントや自動作成ドキュメントなんてやくに立たない」ではなく
        「(ドキュメント作成能力にない人間による)ドキュメントやコメントや自動作成ドキュメントなんてやくに立たない」
        ではないでしょうか。自動生成で「何をしたいか(したかったか)」が出力されるよう書かれたソースなら全て解決。

        • by Anonymous Coward

          「何をしたいか(したかったか)」

          これは理論的にコメントや自動作成ドキュメントからは本質的に作成不可能なんですよ。

          なぜか。

          何かバグがあったとします。
          「何をしたいか、したかったか(要求、仕様、設計)」と「何をしているか(ソースコード)」が乖離しているからバグがあるわけです。結局出来上がるものは本来の「何がしたかったか」はわからないのです。

          なので、自動作成ドキュメントでできたもの(だけ)なんて、メンテ時には役に立たないんですよ。ほとんどの場合。

「科学者は100%安全だと保証できないものは動かしてはならない」、科学者「えっ」、プログラマ「えっ」

処理中...