ドキュメント作成がバグ検出ツールになる？ 65
ストーリー by reo
論文でも似たようなことが… 部門より
論文でも似たようなことが… 部門より
taraiok 曰く、
コードを書くプログラマにとって、ドキュメント制作作業は「本来の仕事とは違う」と思いがちで、基本的には苦痛を伴うもののハズ。Made by Knight のブログ記事 "Documentation as a Bug-Finding Tool" ではバグ発見ツールとしてのドキュメンテーションについて述べられている (本家 /. 記事より) 。
ドキュメントは別の開発者にコードが引き継がれたときに、どのように動作するかという理解させるものだ。書いている自分以外「もう二度と見ないのでは」と思うコードでも、内部構造を手早く要約したドキュメントは、すべてを再チェックして構造を把握し直したり、書いた当時の忘れていた記憶を呼び戻す役割を持つ。しかし、ドキュメントを書くメリットはそれだけではない。書くためにコードを再チェックする過程で、小さなバグを発見できる可能性があるのだ。大きなプログラムになると、小さなバグを見つけるのは困難になる。コードレビューなどのチェッカーとドキュメント制作を組み合わせるだけで、高品質なコードを大量に書き起こすのに役立つだろう。
本家コメントではとある先人の格言が紹介されている。
「コードとドキュメントが合わない場合、それは両方とも間違っている」。
大学で教わりました。 (スコア:5, 興味深い)
こうするとソース見ただけで概要がつかめるし、ドキュメントとコードの齟齬もないということでした。
言われたときにはピンとこなかったんですが、先輩の卒論に添付のソースとドキュメントを読んだ時には納得しました。確かに分かりやすいしコードとドキュメントに矛盾がありません。うまい手だと思いました。
でも、現場の進行を考えると時間食い過ぎで採用されにくい方法だと思います。せっかくの知恵なのに。
Re:大学で教わりました。 (スコア:1)
後輩にソースへのコメント記載の意義を理解してもらうために、こんな説明をしています。
・コードを書く前に処理内容をコメントで書く事
・（設計書がある場合）なるべく設計書の記載を使用する事
・コメントを書いたら、コメント通りにコーディングする事
言葉で説明できないコードを書かなくなるので、意味不明なコードが減ります。
Re: (スコア:0)
これはコードを勉強するための手法では？
Re: (スコア:0)
コーディングしていく過程でどんどん横に流されて
当初の設計の名前がふさわしくなくなっても、「最小限
以外変えてはいかん」という外的・内的プレッシャーで
アホな命名すら、インデントですら、絶対に間違っている
コメントすら変えられなかったりする現場も多いのです。
自分のソースか、人のソースか、という認識の違いでしょうか。
等価変換を一歩踏み出す勇気が欲しいところなんですが
これがなかなか・・・。
3パスプログラミング (スコア:2)
個人的に理想とするプログラミングは３パス方式ですね。
１パス目
主にあたりを取るためや今の考えが適合することを確認するため、情報を取るために
書き散らす。
読めることはあまり気にしない、間違えること・ポカが最小限になるように書いて試す。
２パス目
１パス目の情報より方針が決定され、読めるように、正しく動作するように書き直す。
３パス目
最終確認をしながら、未来の自分に「遺す」ようにコメント・コードを整理する。
２パス目は新規に書き下ろすようなつもりでいます。
２・３パス目ではhexコンペアや exeコンペア [so-net.ne.jp]も活用します。
Re:3パスプログラミング (スコア:4, すばらしい洞察)
間違っています。１パスで書いてください。プログラミングにおいてモックアップを書き散らすなんてことはありえません。コードは常に整理してください。
今、考えられうるかぎり、最もシンプルで、最も実装が早く、要求が満たされる方法を考えて、完成形そのものをコードにしてください。テスト駆動開発して、常に正しく動くようにしてください。
ソフトウェアが成長する過程でより理想的な設計が見つかることもあるでしょう。しかし、それは完成形を目指して書こうとしてるから見つかるのであって、正しく動くかどうか分からないとにかく書いて試す、みたいなものでみつかるものではないでしょう。
正しい設計が見つかったら、そのように書きなおしてテストを通してください。それは１パス目２パス目とか段階踏んでやるものではなく、絶えず行うものです。
Re:3パスプログラミング (スコア:1)
この人は概念実証とかプロトタイピングは決してしないのかな
Re:3パスプログラミング (スコア:1)
uratanとnarucyの書いたコードを実際見比べてみないと何とも言えんな。
両者の生産過程に正誤という程の問題は感じられない。
Re: (スコア:0)
TDDは宗教だと思うな
Re: (スコア:0)
TDDって完成形がいきなりできるものじゃないと思うのですが。
とりあえずおおまかなテスト書く→それを通る部分だけ作る
上よりちょっと細かなテスト書く→それを通る部分だけ作る
繰り返してそのうち完成！
ってアジャイルの本に書いてあったのですが。
ドキュメント駆動作ってくれ (スコア:2)
......それなんてCOBOL。でも今ならもっと進歩してるからもっといいのが出来るはずと、他力本願で待つ。
前か後か (スコア:1)
できあがったものの簡潔な説明は、確かにここで指摘されたように有用だと思う。
けど、設計書にその役割を求めると、理想はともかくとして大概「格言」に引っ掛かることになるよね。
Re:前か後か (スコア:2)
ろくでもないドキュメントの原因は書かせる人が、読む人間でも書く人でもないことだと思うんだ。
Press Enter (スコア:2, 参考になる)
たとえばこんな雰囲気ですね。
http://el.jibun.atmarkit.co.jp/pressenter/2012/02/7-9fcb.html [atmarkit.co.jp]
http://el.jibun.atmarkit.co.jp/pressenter/2012/03/8-4118.html [atmarkit.co.jp]
こういう阿呆が実在すると、首を絞めて、切り落として、ミンチにして犬の餌にでもしたくなる。
Re: (スコア:0)
文書を細かく正確に作る事が、後々混乱を防ぐ良い文書になる事もあるけど、まあ、これはねぇ。
以前、Wordで作ったアンケートに□があって、該当する箇所を■に変更して提出した所、「レ点に描き直して」と言われた事があったけど。
Re:前か後か (スコア:1)
テスト駆動を昇華すればいんじゃないの？
そのうち、ドキュメントを書く⇒テストが自動生成される⇒そのテストを満たしたコードが生成される
ただ、コードとドキュメントが合っていても、両方とも間違っていることもある
Re:前か後か (スコア:1)
Re: (スコア:0)
出来上がったもののを書くのは順番が逆です。ほぼ意味が無い。
ドキュメントとして必要な部分を理解していれば、メンテナンスも困難ではありません。
問題になるとすれば
・必要以上のものを「必須記述項目」として管理しようとしている
・プロジェクト面メンバーの怠惰（後の事、他人のことを考慮しないモラルの低さ）
ぐらいしかなく、それは必ずクリアする必要があるものです。
# 個人や超少人数なら、ほとんどドキュメントは不要かも・・・
Re: (スコア:0)
> ・必要以上のものを「必須記述項目」として管理しようとしている
改版履歴および改変個所の明示
orz
Re: (スコア:0)
設計書は設計書であり、例えばメンテとかに使うには「必要以上」のものが入らざるを得ないと思うんだけど。
Re: (スコア:0)
コードのメンテナンスに限定するのなら、別に作ったドキュメントはあまり役に立ちませんよ。
結局、そのドキュメントに書かれていることが正しいかどうかの確認のため、ソース解析を行うことになりますし。
そんなものに工数をかけるなら、ソースコード上のコメントを増やしてもらった方が解析がはかどります。
システム全体のメンテナンスを行うのならそれは設計の範疇ですから、コードからおこしたドキュメントを使うなんてナンセンスですし。
Re: (スコア:0)
そのコメントが正しいという保証は？
Re: (スコア:0)
それが正しいという保証なのか、間違ってるという保証なのかが人間には判然としないというだけで
Re: (スコア:0)
よく出来たドキュメントのあるプログラムは、プログラム自身が
よく出来ているので、そのドキュメントは参照されないという・・・。
不出来なプログラムには、ドキュメント自体が無い場合が多い。
Re: (スコア:0)
同様の経験は確かにあるが、バグ発見に「も」役立つというだけで、そっちがメインじゃないよな。
その目的のためだけにドキュメントを書かせるならS/N比が悪すぎる。
# この文脈ではバグがSignal。
要は時間をかけてコードを精査して埋もれたバグ発見しろや、だけど使った時間がもったいないから
その分手を動かしてドキュメント残せ。
やっぱり最初から作りこまないのがベストで、そのためのKISS。
プログラマにとって、適切なコメントが入ったシンプルなソースは詳細設計書に勝る。
プログラムは設計書のとおりには動かないけれど、コーディングされているとおりには動く。
Re: (スコア:0)
ここの問題はドキュメント作成にかかるコストが書かれていないし、効果についても定量的に書かれていない。
どういったドキュメントをどのくらいの手間をかけて作成するべきかを明示して欲しいよね。
開発時の品質向上の効果についてはわからんが、開発後の保守を担当させられた経験上からは、
肝心なドキュメントが足りなかったり、コードとの間に数箇所の違いがあるだけで、ドキュメントの正当性が怪しくなり、
最終的にはソースを見ないと駄目という結論に・・・
ソース見れる奴はどうせドキュメントなんて見ないのさ（笑）
簡潔に説明する文章だけならいいんだよ (スコア:1)
微細に書かせるから書きたくなくなるんだよ。
# ドキュメント？欲しけりゃくれてやる
# 俺の全てをソースに置いてきた
Re:簡潔に説明する文章だけならいいんだよ (スコア:1)
Re: (スコア:0)
ソースちゅうのはミクロな視点なので、マクロな視点の
読み物は別途あると便利ですよね。
各モジュールの目指す役割など、つーかどのソースをまず
あたればいいのかがわかるものが、ざっとでも書いてあると
うれしい。
あと当初の考えが甘くて苦労したポイントなどが書いてあると
それだけでもそこが要注意だとわかる。
Re:簡潔に説明する文章だけならいいんだよ (スコア:1)
ソースは結論しか書いてないからその経緯がほしいんですよね
何のためにわざわざこんな実装なのか、とか
これは何を意味する処理なのか、とか。
ソースコメントは本人視点になりやすくドキュメントは第三者視点になりやすい。
倒産した会社のソースを引き継いだときに渇望したのは
要件定義と倒産までの運用内容の経緯でした。
ソースなんて読みゃわかるし。
Re: (スコア:0)
実装詳細をいちいち微細に書かせてたんならそう言いたくなるのは当然だよね。
もし詳細な仕様を書かされたと文句言ってるのなら首切って排除するのが上司の仕事だけど。
# 俺の全てをソースに置いてきた
と言ってる所を見る限り怪しいけどこれだけでは判断できないな。
Re: (スコア:0)
実装詳細を仕様書に書け仕様書に書けと上（主に一時請け）が口をすっぱくして言うので、最終的にソースをWordにコピペして変数名などを日本語に直した、という事態を何度も体験したことがあります。
詳細に書けはそういう事態を招くので、適切な粒度を指定しないと危ないです。
つーか、本当に詳細な設計書は製造レベルで考えないといけないので、それだったら製造したほうが早い→ソースを設計書にコピペ、という空気になりがち。
（特にスケジュールが押してて、仕様書が納品物だと。）
そしてそんな設計書であれば、始めからソースを読んだ方が早いの
Joel on Software (スコア:1)
ドキュメント？ (スコア:0)
ああ、書いてやるよ。俺だって必要だと思ってるから、いくらでも書いてやる
但し、俺の書きやすいフォーマットでな！
＃WordとExcelは勘弁な
Re: (スコア:0)
了解いたしました。
その代わり、不明点の確認や修正依頼は随時させていただきますので…
「コードとドキュメントが合わない場合、それは両方とも間違っている」 (スコア:0)
ごもっとも
でも、ソースコードの中のコメントからして、ソースの中身と合ってないこともままあったりして orz
Re:「コードとドキュメントが合わない場合、それは両方とも間違っている」 (スコア:1)
でも、ソースコードの中のコメントからして、ソースの中身と合ってないこともままあったりして orz
間違っていても、書いてあるだけ有難いと思えることもままあったりします orz
中国語でもハングルでも構いませんので。
Re: (スコア:0)
設計書と合っていないこともままあったりします orz
Re: (スコア:0)
顧客の要望とも会ってないことも・・・ orz
Re: (スコア:0)
顧客の要望はそもそもコロコロ内容が変わったり自己矛盾していたりするのでどうしようもない。せめて変わったという客観的な証拠を残すために文書化が必要
Re: (スコア:0)
トラップです。コメントのコピペ禁止だ！ｗ全然違う処理なのに全部同じコメントが・・・あとで修正するつもりだったんだろな
あと、「念のため」というコメントがいっぱいあるソースとかもいやです。
コピーできるぐらいに文書化するから技術が漏れる (スコア:0)
職人の頭の中にだけあればいいものを他国へわざわざ教えようとする間違った文化の紹介方法はいい加減にやめてほしい
Re: (スコア:0)
で、職人がトラックにひかれて技術が失われると
Re: (スコア:0)
技術が失われてもったいないのと、
他人に悪用されてもったいないのは別
「本来の仕事」とは (スコア:0)
ドキュメント制作作業は「本来の仕事とは違う」
ってあるけど、本来の仕事って何なの？
「三人のレンガ積み」って程じゃないけど、
プログラマの仕事は、顧客の要望を満たすことやユーザに満足してもらうことでしょ。
そのためにWebサービスなりがあって、そのWebサービスを作るためにプログラミングをするんじゃないの？
そして継続して使ってもらうために保守性が必要でドキュメントが必要だったりするわけで
ドキュメント制作作業は「本来の仕事とは違う」
なんて言い出す奴とは一緒に仕事したくないね。技術者として情けない。
Re:「本来の仕事」とは (スコア:1)
完璧な仕様書の類がそろっているバグだらけのプログラムと、
ドキュメントが一切ないがバグのないプログラムのどちらが欲しいですか?
ま、設問自体が無茶な話ですが。
発注元・開発元・ユーザといったそれぞれの立場や継続的なメンテナンスの
要不要で答えは変わってきます。
組込屋の立場からは、最終的にユーザの手元でプログラムがまともに動いて
本来の機能をはたしてくれることをなによりも優先させたい。
ドキュメントを作りたくないんじゃなくて、金銭的/納期的に不十分な状況で
どうバランスとるか、の配分の問題でしょ。
Re: (スコア:0)
> ドキュメントが一切ないがバグのないプログラムのどちらが欲しいですか?
開発者の立場として言うと、ある挙動がバグなのか仕様なのかすらわからないプロジェクトはまず炎上します。
既にソフト作ってしまったのに、仕様の決定からやり直さないといけないようなプロジェクトには近寄りたくないものです。
カスタマイズ地獄 (スコア:0)
そうですね。受け入れ検査ができる程度のほどほどのドキュメントと通常の定型作業では不具合が発生しない程度のプログラムを予算内の人件費で作ることが求められているのが大概です。
ドキュメントが一切ないがバグのないプログラムというのは、プログラムの受け入れ検査ができない時点で、納品が完了できません。つまり、お金にならない。下手するとプログラムだけ顧客に持ち逃げされる。
完璧な仕様書の類がそろっているバグだらけのプログラムなら、既存障害リストがあれば納品できる可能性がある。もっとも、納品した後に、スルガ銀行がＩＢＭを訴えたように、顧客に訴えられたり、次の仕事が来なかったりする可能性は残る。
Re: (スコア:0)
>ドキュメント制作作業は「本来の仕事とは違う」
>ってあるけど、本来の仕事って何なの？
コーディングに3日、見積もりも3日
ほら、ドキュメント制作作業が見積もられてない！！
本来の仕事じゃないよね？
Re:「本来の仕事」とは (スコア:1)
>ほら、ドキュメント制作作業が見積もられてない！！
これに尽きるよなあ・・。
お客さんに出すドキュメントは必要なくても、瑕疵対応なんかで社内用には必要なのに。
それを知らないのか、営業は嬉しそうに「予算が無いからドキュメントなしで」なんて言ってくれるし。