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

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

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

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

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

    • Re: (スコア:5, すばらしい洞察)

      by Anonymous Coward

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

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

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

      極端に抽象化した話、
      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」が「何をしたいのか?」って点で表現されている物の方がずっと良い。

物事のやり方は一つではない -- Perlな人

処理中...