パスワードを忘れた? アカウント作成
2658587 story
プログラミング

ドキュメント作成がバグ検出ツールになる? 65

ストーリー by reo
論文でも似たようなことが… 部門より

taraiok 曰く、

コードを書くプログラマにとって、ドキュメント制作作業は「本来の仕事とは違う」と思いがちで、基本的には苦痛を伴うもののハズ。Made by Knight のブログ記事 "Documentation as a Bug-Finding Tool" ではバグ発見ツールとしてのドキュメンテーションについて述べられている (本家 /. 記事より) 。

ドキュメントは別の開発者にコードが引き継がれたときに、どのように動作するかという理解させるものだ。書いている自分以外「もう二度と見ないのでは」と思うコードでも、内部構造を手早く要約したドキュメントは、すべてを再チェックして構造を把握し直したり、書いた当時の忘れていた記憶を呼び戻す役割を持つ。しかし、ドキュメントを書くメリットはそれだけではない。書くためにコードを再チェックする過程で、小さなバグを発見できる可能性があるのだ。大きなプログラムになると、小さなバグを見つけるのは困難になる。コードレビューなどのチェッカーとドキュメント制作を組み合わせるだけで、高品質なコードを大量に書き起こすのに役立つだろう。

本家コメントではとある先人の格言が紹介されている。

「コードとドキュメントが合わない場合、それは両方とも間違っている」。

この議論は賞味期限が切れたので、アーカイブ化されています。 新たにコメントを付けることはできません。
  • by prankster (12979) on 2012年04月18日 12時05分 (#2138198)
    研究室配属になってコード書きだしたころに先生(助手)から指示がありました。

    コードを書きながらできるだけ詳細にコメントを付ける。
    書きあがったらバグ出ししつつコメントも修正する。
    できあがったらコメントを読みつつドキュメントを書く。

    こうするとソース見ただけで概要がつかめるし、ドキュメントとコードの齟齬もないということでした。

    言われたときにはピンとこなかったんですが、先輩の卒論に添付のソースとドキュメントを読んだ時には納得しました。確かに分かりやすいしコードとドキュメントに矛盾がありません。うまい手だと思いました。

    でも、現場の進行を考えると時間食い過ぎで採用されにくい方法だと思います。せっかくの知恵なのに。

    • by Anonymous Coward on 2012年04月18日 12時28分 (#2138227)

      後輩にソースへのコメント記載の意義を理解してもらうために、こんな説明をしています。

      ・コードを書く前に処理内容をコメントで書く事
      ・(設計書がある場合)なるべく設計書の記載を使用する事
      ・コメントを書いたら、コメント通りにコーディングする事

      言葉で説明できないコードを書かなくなるので、意味不明なコードが減ります。

      親コメント
    • by Anonymous Coward

      これはコードを勉強するための手法では?

    • by Anonymous Coward

      コーディングしていく過程でどんどん横に流されて
      当初の設計の名前がふさわしくなくなっても、「最小限
      以外変えてはいかん」という外的・内的プレッシャーで
      アホな命名すら、インデントですら、絶対に間違っている
      コメントすら変えられなかったりする現場も多いのです。
      自分のソースか、人のソースか、という認識の違いでしょうか。
      等価変換を一歩踏み出す勇気が欲しいところなんですが
      これがなかなか・・・。

  • 個人的に理想とするプログラミングは3パス方式ですね。
    1パス目
     主にあたりを取るためや今の考えが適合することを確認するため、情報を取るために
     書き散らす。
     読めることはあまり気にしない、間違えること・ポカが最小限になるように書いて試す。
    2パス目
     1パス目の情報より方針が決定され、読めるように、正しく動作するように書き直す。
    3パス目
     最終確認をしながら、未来の自分に「遺す」ようにコメント・コードを整理する。

    2パス目は新規に書き下ろすようなつもりでいます。
    2・3パス目ではhexコンペアや exeコンペア [so-net.ne.jp]も活用します。

    • Re:3パスプログラミング (スコア:4, すばらしい洞察)

      by deleted user (13014) on 2012年04月18日 16時24分 (#2138406)

      間違っています。1パスで書いてください。プログラミングにおいてモックアップを書き散らすなんてことはありえません。コードは常に整理してください。

      今、考えられうるかぎり、最もシンプルで、最も実装が早く、要求が満たされる方法を考えて、完成形そのものをコードにしてください。テスト駆動開発して、常に正しく動くようにしてください。

      ソフトウェアが成長する過程でより理想的な設計が見つかることもあるでしょう。しかし、それは完成形を目指して書こうとしてるから見つかるのであって、正しく動くかどうか分からないとにかく書いて試す、みたいなものでみつかるものではないでしょう。

      正しい設計が見つかったら、そのように書きなおしてテストを通してください。それは1パス目2パス目とか段階踏んでやるものではなく、絶えず行うものです。

      親コメント
      • by Anonymous Coward on 2012年04月18日 20時12分 (#2138519)

        この人は概念実証とかプロトタイピングは決してしないのかな

        親コメント
      • by Anonymous Coward on 2012年04月19日 2時32分 (#2138682)

        uratanとnarucyの書いたコードを実際見比べてみないと何とも言えんな。
        両者の生産過程に正誤という程の問題は感じられない。

        親コメント
      • by Anonymous Coward

        TDDは宗教だと思うな

      • by Anonymous Coward

        TDDって完成形がいきなりできるものじゃないと思うのですが。
        とりあえずおおまかなテスト書く→それを通る部分だけ作る
        上よりちょっと細かなテスト書く→それを通る部分だけ作る
        繰り返してそのうち完成!
        ってアジャイルの本に書いてあったのですが。

  • ドキュメント書いたらそれがそのまま動くようにしてくれ。
    ......それなんてCOBOL。でも今ならもっと進歩してるからもっといいのが出来るはずと、他力本願で待つ。
  • by sarasara (45273) on 2012年04月18日 11時06分 (#2138140)

    できあがったものの簡潔な説明は、確かにここで指摘されたように有用だと思う。
    けど、設計書にその役割を求めると、理想はともかくとして大概「格言」に引っ掛かることになるよね。

    • by johndoe (3028) on 2012年04月18日 12時55分 (#2138267) 日記

      ろくでもないドキュメントの原因は書かせる人が、読む人間でも書く人でもないことだと思うんだ。

      親コメント
    • by Anonymous Coward on 2012年04月18日 11時41分 (#2138178)

      テスト駆動を昇華すればいんじゃないの?
      そのうち、ドキュメントを書く⇒テストが自動生成される⇒そのテストを満たしたコードが生成される

      ただ、コードとドキュメントが合っていても、両方とも間違っていることもある

      親コメント
    • by Anonymous Coward

      出来上がったもののを書くのは順番が逆です。ほぼ意味が無い。
      ドキュメントとして必要な部分を理解していれば、メンテナンスも困難ではありません。

      問題になるとすれば
       ・必要以上のものを「必須記述項目」として管理しようとしている
       ・プロジェクト面メンバーの怠惰(後の事、他人のことを考慮しないモラルの低さ)
      ぐらいしかなく、それは必ずクリアする必要があるものです。

      # 個人や超少人数なら、ほとんどドキュメントは不要かも・・・

      • by Anonymous Coward

        > ・必要以上のものを「必須記述項目」として管理しようとしている

        改版履歴および改変個所の明示

        orz

      • by Anonymous Coward

        設計書は設計書であり、例えばメンテとかに使うには「必要以上」のものが入らざるを得ないと思うんだけど。

        • by Anonymous Coward

          コードのメンテナンスに限定するのなら、別に作ったドキュメントはあまり役に立ちませんよ。
          結局、そのドキュメントに書かれていることが正しいかどうかの確認のため、ソース解析を行うことになりますし。
          そんなものに工数をかけるなら、ソースコード上のコメントを増やしてもらった方が解析がはかどります。

          システム全体のメンテナンスを行うのならそれは設計の範疇ですから、コードからおこしたドキュメントを使うなんてナンセンスですし。

          • by Anonymous Coward

            そのコメントが正しいという保証は?

            • by Anonymous Coward
              大抵の場合はその下に機械可読な形式で厳密に書いてあるよ。
              それが正しいという保証なのか、間違ってるという保証なのかが人間には判然としないというだけで
    • by Anonymous Coward

      よく出来たドキュメントのあるプログラムは、プログラム自身が
      よく出来ているので、そのドキュメントは参照されないという・・・。
      不出来なプログラムには、ドキュメント自体が無い場合が多い。

    • by Anonymous Coward

      同様の経験は確かにあるが、バグ発見に「も」役立つというだけで、そっちがメインじゃないよな。
      その目的のためだけにドキュメントを書かせるならS/N比が悪すぎる。
      # この文脈ではバグがSignal。
      要は時間をかけてコードを精査して埋もれたバグ発見しろや、だけど使った時間がもったいないから
      その分手を動かしてドキュメント残せ。

      やっぱり最初から作りこまないのがベストで、そのためのKISS。
      プログラマにとって、適切なコメントが入ったシンプルなソースは詳細設計書に勝る。
      プログラムは設計書のとおりには動かないけれど、コーディングされているとおりには動く。

      • by Anonymous Coward

        ここの問題はドキュメント作成にかかるコストが書かれていないし、効果についても定量的に書かれていない。
        どういったドキュメントをどのくらいの手間をかけて作成するべきかを明示して欲しいよね。

        開発時の品質向上の効果についてはわからんが、開発後の保守を担当させられた経験上からは、
        肝心なドキュメントが足りなかったり、コードとの間に数箇所の違いがあるだけで、ドキュメントの正当性が怪しくなり、
        最終的にはソースを見ないと駄目という結論に・・・

        ソース見れる奴はどうせドキュメントなんて見ないのさ(笑)

  • 微細に書かせるから書きたくなくなるんだよ。

    # ドキュメント?欲しけりゃくれてやる
    # 俺の全てをソースに置いてきた

    • 首切られるんですかい
      親コメント
    • by Anonymous Coward

      ソースちゅうのはミクロな視点なので、マクロな視点の
      読み物は別途あると便利ですよね。
      各モジュールの目指す役割など、つーかどのソースをまず
      あたればいいのかがわかるものが、ざっとでも書いてあると
      うれしい。
      あと当初の考えが甘くて苦労したポイントなどが書いてあると
      それだけでもそこが要注意だとわかる。

      • by Anonymous Coward on 2012年04月18日 20時25分 (#2138528)

        ソースは結論しか書いてないからその経緯がほしいんですよね
        何のためにわざわざこんな実装なのか、とか
        これは何を意味する処理なのか、とか。
        ソースコメントは本人視点になりやすくドキュメントは第三者視点になりやすい。

        倒産した会社のソースを引き継いだときに渇望したのは
        要件定義と倒産までの運用内容の経緯でした。
        ソースなんて読みゃわかるし。

        親コメント
    • by Anonymous Coward

      実装詳細をいちいち微細に書かせてたんならそう言いたくなるのは当然だよね。
      もし詳細な仕様を書かされたと文句言ってるのなら首切って排除するのが上司の仕事だけど。

      # 俺の全てをソースに置いてきた
      と言ってる所を見る限り怪しいけどこれだけでは判断できないな。

      • by Anonymous Coward

        実装詳細を仕様書に書け仕様書に書けと上(主に一時請け)が口をすっぱくして言うので、最終的にソースをWordにコピペして変数名などを日本語に直した、という事態を何度も体験したことがあります。

        詳細に書けはそういう事態を招くので、適切な粒度を指定しないと危ないです。
        つーか、本当に詳細な設計書は製造レベルで考えないといけないので、それだったら製造したほうが早い→ソースを設計書にコピペ、という空気になりがち。
        (特にスケジュールが押してて、仕様書が納品物だと。)
        そしてそんな設計書であれば、始めからソースを読んだ方が早いの

  • by Anonymous Coward on 2012年04月18日 12時11分 (#2138207)

    ああ、書いてやるよ。俺だって必要だと思ってるから、いくらでも書いてやる
    但し、俺の書きやすいフォーマットでな!

    #WordとExcelは勘弁な

    • by Anonymous Coward

      了解いたしました。

      その代わり、不明点の確認や修正依頼は随時させていただきますので…

  • ごもっとも

    でも、ソースコードの中のコメントからして、ソースの中身と合ってないこともままあったりして orz

    • でも、ソースコードの中のコメントからして、ソースの中身と合ってないこともままあったりして orz

      間違っていても、書いてあるだけ有難いと思えることもままあったりします orz
      中国語でもハングルでも構いませんので。

      親コメント
    • by Anonymous Coward

      設計書と合っていないこともままあったりします orz

      • by Anonymous Coward

        顧客の要望とも会ってないことも・・・ orz

        • by Anonymous Coward

          顧客の要望はそもそもコロコロ内容が変わったり自己矛盾していたりするのでどうしようもない。せめて変わったという客観的な証拠を残すために文書化が必要

    • by Anonymous Coward

      トラップです。コメントのコピペ禁止だ!w全然違う処理なのに全部同じコメントが・・・あとで修正するつもりだったんだろな
      あと、「念のため」というコメントがいっぱいあるソースとかもいやです。

  • by Anonymous Coward on 2012年04月18日 12時15分 (#2138211)

    職人の頭の中にだけあればいいものを他国へわざわざ教えようとする間違った文化の紹介方法はいい加減にやめてほしい

    • by Anonymous Coward

      で、職人がトラックにひかれて技術が失われると

      • by Anonymous Coward

        技術が失われてもったいないのと、
        他人に悪用されてもったいないのは別

  • by Anonymous Coward on 2012年04月18日 12時41分 (#2138248)

    ドキュメント制作作業は「本来の仕事とは違う」
    ってあるけど、本来の仕事って何なの?

    「三人のレンガ積み」って程じゃないけど、
    プログラマの仕事は、顧客の要望を満たすことやユーザに満足してもらうことでしょ。
    そのためにWebサービスなりがあって、そのWebサービスを作るためにプログラミングをするんじゃないの?

    そして継続して使ってもらうために保守性が必要でドキュメントが必要だったりするわけで
    ドキュメント制作作業は「本来の仕事とは違う」
    なんて言い出す奴とは一緒に仕事したくないね。技術者として情けない。

    • by Anonymous Coward on 2012年04月18日 15時12分 (#2138362)

      完璧な仕様書の類がそろっているバグだらけのプログラムと、
      ドキュメントが一切ないがバグのないプログラムのどちらが欲しいですか?

      ま、設問自体が無茶な話ですが。
      発注元・開発元・ユーザといったそれぞれの立場や継続的なメンテナンスの
      要不要で答えは変わってきます。

      組込屋の立場からは、最終的にユーザの手元でプログラムがまともに動いて
      本来の機能をはたしてくれることをなによりも優先させたい。
      ドキュメントを作りたくないんじゃなくて、金銭的/納期的に不十分な状況で
      どうバランスとるか、の配分の問題でしょ。

      親コメント
      • by Anonymous Coward

        > ドキュメントが一切ないがバグのないプログラムのどちらが欲しいですか?
        開発者の立場として言うと、ある挙動がバグなのか仕様なのかすらわからないプロジェクトはまず炎上します。
        既にソフト作ってしまったのに、仕様の決定からやり直さないといけないようなプロジェクトには近寄りたくないものです。

      • by Anonymous Coward

        そうですね。受け入れ検査ができる程度のほどほどのドキュメントと通常の定型作業では不具合が発生しない程度のプログラムを予算内の人件費で作ることが求められているのが大概です。

        ドキュメントが一切ないがバグのないプログラムというのは、プログラムの受け入れ検査ができない時点で、納品が完了できません。つまり、お金にならない。下手するとプログラムだけ顧客に持ち逃げされる。

        完璧な仕様書の類がそろっているバグだらけのプログラムなら、既存障害リストがあれば納品できる可能性がある。もっとも、納品した後に、スルガ銀行がIBMを訴えたように、顧客に訴えられたり、次の仕事が来なかったりする可能性は残る。

    • by Anonymous Coward

      >ドキュメント制作作業は「本来の仕事とは違う」
      >ってあるけど、本来の仕事って何なの?

      コーディングに3日、見積もりも3日
      ほら、ドキュメント制作作業が見積もられてない!!
      本来の仕事じゃないよね?

      • by Anonymous Coward on 2012年04月18日 17時17分 (#2138426)

        >ほら、ドキュメント制作作業が見積もられてない!!

        これに尽きるよなあ・・。

        お客さんに出すドキュメントは必要なくても、瑕疵対応なんかで社内用には必要なのに。
        それを知らないのか、営業は嬉しそうに「予算が無いからドキュメントなしで」なんて言ってくれるし。

        親コメント
typodupeerror

弘法筆を選ばず、アレゲはキーボードを選ぶ -- アレゲ研究家

読み込み中...