報告とは？/ レイク
[ 549] 効果的にバグを報告するには
[引用サイト] http://www.unixuser.org/~ueno/bugs-ja.html
|
中山洋一さんと武井伸光さんに、日本語の不自然な箇所や訳文の不明確な点を修正して頂きました。どうもありがとうございます。 誰でも、公衆利用のためのソフトウェアを書いたなら、おそらく一通以上の悪いバグ報告を受け取るはめになるだろう。何も言わんとしない報告（「動きません！」）、意味をなさない報告、十分な情報を供さない報告、誤った情報を与える報告。利用者の思い違いが原因の報告、誰か他の人のプログラムの欠陥が原因の報告、ネットワークの故障が原因の報告。 技術的なサポートが、ぞっとする仕事とみなされてきたのには理由がある。それは悪いバグ報告が送られて来るからである。とはいえ、バグ報告は不快なものばかりではない。私は食い扶持を稼ぐのとは別にフリーソフトウェアを保守しているが、たまに素晴しく明快で有益な、情報量の多いバグ報告を受け取ることがある。 このエッセイで私は、どうすれば良いバグ報告ができるのかはっきり述べようと思う。願わくは世界中の全ての人に、誰かに何らかのバグを報告する前にこのエッセイを読んでもらいたい。特に私にバグを報告する人にはよく読んで欲しい。 一言で言うと、バグ報告のねらいは、プログラムが失敗することをプログラマの目の前で分からせることである。直接見せてもいいし、プログラムを失敗させるための入念で詳細な指示書を与えても良い。プログラムを失敗させることができたら、原因が分かるまでプログラマは追加の情報を集めようとするだろう。プログラムを失敗させることができなかったら、プログラマは追加の情報を集めてくれるようあなたに頼まざるを得なくなる。 バグ報告では、現実に起こったこと（「コンピュータに向かっていたらこんなことが起こりました」）と憶測（「この問題はこうだと思う」）とを明確にするよう心掛けよう。憶測は省きたいなら省いてもいいが、事実を省いてはならない。 あなたはバグが修正されることを望んでいるからバグを報告をするのであって、プログラマを罵ったり、わざと役に立たなかろうとするのは意味がない。バグはあなたにとって問題で、それは彼らの落度かもしれないから、あなたが怒るのも無理はないが、あなたが彼らの欲しがっている情報を全て与えることで役に立てば、バグはそれだけ早く修正されるだろう。また、プログラムがフリーなら、作者は親切心からそれを提供しているのであり、あまりにも沢山の人々が彼らに礼をわきまえなければ、彼らはその思いやりをなくしてしまうかもしれないことを心に留めておこう。 プログラマには基本的な知恵が備わっていると信じよう。そのプログラムが本当に全く動かないのなら、彼らはおそらく気付いているだろうし、気付いていないのなら、彼らのところでは動いているに違いない。従って、あなたが彼らと異なったやりかたをしているか、あなたの環境が彼らのものと異なっている。彼らは情報を欲しがっていて、この情報を提供することがバグ報告の目的である。情報は多ければ多いほどいい。 多くのプログラム、特にフリーのものは、既知のバグの一覧を公開している。もし既知のバグの一覧を見付けることができたなら、あなたがちょうど見付けたバグが既知のものかどうかを調べるために読む価値がある。もし既知のものなら、多分、改めて報告する価値はない。しかし、もしバグ一覧にある報告より、あなたのほうが多くの情報を持っていると思うのなら、やはりプログラマに連絡を取りたくなるかもしれない。彼らが知らない情報を与えることができたら、彼らはもっと簡単にバグを修正できるだろう。 このエッセイには指標が満載されている。どれも絶対的な規則ではないけれど。特別な方法でのバグ報告を望むプログラマもいる。プログラムにバグ報告の指標が付いてきたなら、それを読もう。もしプログラムに付いてきた指標と、このエッセイの指標が矛盾するのなら、プログラムに付いてきたほうに従おう！ バグを報告するのではなくて、単にプログラム使用上の助けを求めるなら、疑問を解決するためにどの辺を見たのか明示しよう。（「４章の５．２節の中を参照しましたが、これが可能かどうか示すものは見当たりませんでした」）これにより、プログラマは人々が答えを期待する場所を知り、文書を使い易くすることができる。 バグを報告する一番良い方法の一つは、プログラマに見せることである。彼らをあなたのコンピュータの前に立たせ、ソフトウェアを立ち上げ、具合が悪くなることを実際にやって見せよう。マシンを起動するのを見せ、ソフトウェアを走らせるのを見せ、どんな風にソフトウェアと戯れるかを見せ、入力に対してソフトウェアがどう反応するかを見せよう。 プログラマはソフトウェアを隅々まで熟知している。彼らはどの部分が信頼できるか、どの部分に欠陥がありそうか知っている。彼らは直感的に、何を見ればいいか知っている。ソフトウェアが明らかにおかしくなるまでに、彼らは手がかりとなる、先行する微妙におかしなことに気付くだろう。試験動作中、彼らはコンピュータが行う全てを観察し、彼らにとって重要な場面を見付け出す。 これで十分ではないかもしれない。彼らはより多くの情報が必要だと判断し、もう一度同じことを見せるよう頼むかもしれない。バグを彼ら自身で何度でも再現できるよう、手順の途中で話し掛けられるかもしれない。手順の変種を数回試し、問題が唯一の場合に起こるのか、一群の関連した場合に起こるのかを調べることもあり得る。もし運が悪ければ、彼らは開発道具と共に二時間座り込んで本当に調査を始めてしまうかもしれない。一番重要なことは、コンピュータがおかしくなったときに、プログラマに見せることである。一度問題が起こるのを見ることができれば、大抵は彼らはそこから問題を見出し、修正し始めるだろう。 インターネットの時代である。世界規模のコミュニケーションの時代である。最近ではボタンに触れるだけでロシアにいる誰かにソフトウェアを送ることができるし、それに対するコメントも同じくらい簡単に返信できる。しかし、プログラムに問題があったら、プログラムがしくじる場面に突き合わせることはできない。「見せてください」と言えれば良いが、大抵はそうすることができない。 直接居合わせないプログラマにバグを報告しなければならないのなら、次なるねらいは彼らに問題を再現できるようにすることである。プログラマにプログラムの複製を走らせ、同じことをさせ、同じ方法で失敗させられればいい。彼らも目の前で問題が起こるのが分かれば処理できる。 だから厳密に何をしたか伝えよう。グラフィカルなプログラムなら、どのボタンを押したのか、どんな順番で押したのかを伝えよう。コマンドをタイプして走るプログラムなら、タイプしたコマンドを正確に教えよう。可能ならいつでも、タイプしたコマンドと応答するコンピュータの出力を表すセッションの一字一句そのままの複製を与えよう。 プログラマには、考えられる全ての入力を与えよう。プログラムがファイルを読むなら、おそらくそのファイルの複製を送る必要があるだろう。プログラムが別のコンピュータとネットワーク越しに会話するなら、そのコンピュータの複製は送れなくても、少なくともそれがどんな種類のコンピュータかを言うことができるし、（できるなら）どのソフトウェアが走っているかを言うことができる。 プログラマに入力とアクションの長い一覧をあげて、彼らが手元にあるプログラムを立ち上げて何もおかしくならなければ、十分な情報を与えなかったということだ。あるいはその欠陥が全てのコンピュータでは顕在しなくて、あなたのコンピュータのどこかが異なっているか、あるいはそのプログラムに想定された動作を誤解していて、まったく同じ表示を見ていても、あなたはおかしいと感じ、彼らはそれが正しいと知っている。 だからまた、何が起こったかを言葉で述べよう。見たことを正確に、どうしてそれがおかしいと思うのかを伝えよう。どうなるべきだと思うのかを伝えればさらにいい。「〜したらおかしくなりました」と言うと、重大な情報のいくつかを省いたことになる。 エラーメッセージを見たら、それがどんなものだったかを注意深く正確にプログラマに伝えよう。エラーメッセージは重要だ！この段階では、プログラマは問題を修正しようとはしていない。ただそれを見付けようとしているだけだ。彼らは何がおかしいのか知る必要があり、これらのエラーメッセージはコンピュータがあなたに伝える最大の努力の成果だ。覚えておくのに他に簡単な方法がないなら、エラーを書き留めよう。どんなエラーメッセージだったかを報告できないのなら、プログラムがエラーを起こしたと報告しても意味はない。 特に、エラーメッセージに数字が含まれるなら、プログラマにそれらの数字を渡そう。あなたにはそれらの意味が見出せないかもしれないが、それはすなわちそこに何もないというわけではないのだから。数字はプログラマが読み得る全ての種類の情報を含んでいて、それらは得てしてきわめて重大な手がかりとなる。エラーメッセージの数字は、コンピュータがあまりに混乱してエラーを言葉で報告できないためにある。しかしコンピュータはベストを尽くし、重要な情報をなんとか伝えようとしているのである。 この段階では、プログラマは探偵になりきって仕事をしている。何が起こったか知らないし、起こるところを監視できるほど十分に突き詰めることはできない。だから正体を明らかにするだろう手がかりを探している。不可解な文字列や数字からなるエラーメッセージや、解明されざる遅延でさえ、まさに全ては殺人のシーンの指紋と同じくらい重要だ。それらを捨てないように！ Ｕｎｉｘを使っているなら、プログラムはコアダンプするかもしれない。ｃｏｒｅはとりわけ良い手がかりの源である。だから捨てないで。とは言うものの、ほとんどのプログラマは巨大なｃｏｒｅファイルを予告なしに電子メールで受け取るのを嫌う。だから誰かにメールする前には尋ねよう。また、ｃｏｒｅファイルにはプログラムの完全な状態が記録されていることに気を付けよう。どんな附随する秘密（たぶんプログラムが個人のメッセージを扱ったり、機密のデータを処理したりして）が含まれているとも限らないのだから。 エラーやバグが起きたときに、やってしまいがちなことは沢山ある。それらの多くは問題を悪化させる。学校の私の友達は、専門家に助けを呼ぶ前に彼女のＷｏｒｄの文書を誤って全部消してしまった。彼女はＷｏｒｄを再インストールし、デフラグしようとした。これらはどちらも彼女のファイルを修復する役には立たないどころか、それらによって彼女のディスクは世界中のどの消去取消プログラムでも一切修復できないほどにごちゃまぜになった。彼女がそのままにしていたらチャンスはあったかもしれないのに。 こういった利用者は隅に追い詰められたマングースに似ていて、何もしないよりは何かしたほうがましに違いないと、背水の陣でやみくもに攻撃する。これはコンピュータの生み出すタイプの問題ではうまくいかない。 マングースになるかわりに羚羊になろう。羚羊は予期せぬか驚くべき事態に直面するとじっと動かなくなる。止まって考え、いちばん良い方策に思いを巡らせている間、まったく黙ったまま、どんな注意をも引かないよう試みる。（もし羚羊に技術的なサポートの回線があったなら、この時点で電話をかけることだろう）それから、いったん安全な方策を決意したら、それをする。 おかしくなったら、何かをするのはすぐにやめよう。どのボタンにも一切触れないように。スクリーンを見て気付いた、不自然な全てを覚えるか書き留めよう。それから初めて、「ＯＫ」か「キャンセル」のどちらか安全そうなほうを押せる。コンピュータが予期せぬことを始めたら、じっと動かなくなる習慣を身につけよう。 問題から抜け出そうと頑張るなら、影響を受けたプログラムを閉じるか、コンピュータを再起動するかして、もう一度それを起こせるようにするのが望ましい。プログラマは一回以上再現可能な問題を好む。幸運なプログラマは早いうちに、より効果的にバグを修正する。 悪いバグ報告を生み出すのは非プログラマだけではない。私が見てきた中で最悪のバグ報告のいくつかは、プログラマから寄せられたものだ。その中には良いプログラマもいる。 かつて私は別のプログラマと仕事をしていた。彼は自身のコードにバグを見つけては、それらを修正しようとしていた。彼は解決できないバグに出会うと助けを求めて頻繁に私を呼び寄せた。「どこがおかしくなったの？」と私が尋ねたら、返事として、修正するのに何が必要か彼の現在の見解を伝えられた。 彼の現在の見解が正しいときには、これはうまくいった。このことは彼が既に仕事の半分を済ませていて、我々は一緒に仕事を完了できることを意味している。効果的で有用だ。 しかし頻繁に彼は間違った。プログラムのいくつかの特定な部分がどうして不正なデータを生み出しているのかを見抜こうと時間を費し、やがてそうはならないことが分かった。事実上の問題は他にあるのに、完全に良いコード片を半時間調査していたことになる。 彼は医者に対してはそんなことをしないだろうと思う。「先生、ハイドロヨーヨーダインの処方箋を出してください」とか。人々はそんなことを医者に言うべきではないと知っているから、現実の不快感や鈍痛、苦痛、発疹、熱といった症状を訴えて、問題が何なのか、それについてどうするべきなのか医者に診断させる。さもなくば医者はあなたを変人だと追い払うに違いない。 これはプログラマにとっても同じだ。あなた自身による診断もたまには役に立つが、いつでも症状を述べるようにしよう。診断は任意の余分なものであって、症状を訴える代わりにはならない。同様に、問題を修正するための、コードへの変更を添えてバグ報告を送るのは有用だが、前者はバグ報告の代用としては十分ではない。 プログラマがあなたに追加の情報を求めてきたら、それを捏造しないように！かつてバグを報告した人に、動かないことが分かっているコマンドを試してくれるよう頼んだことがある。試してくれるよう彼に頼んだ理由は、それにより得られる二つの異なったエラーメッセージを知りたかったからだ。どんなエラーが返ってくるかを知るのは、きわめて重大な手がかりとなる。しかし彼は実際には試さずに、「いいえ、それは動かないでしょう」というメールを返してきた。本当に試すよう彼を説得するのにしばらく時間がかかった。 プログラマに役立つために、知性を使うのは立派だ。たとえ推論が間違っていたとしても、プログラマはあなたが何はともあれ手間を省こうとしてくれたことに感謝するはずだ。けれども、同様に症状を報告しよう。さもなくば逆に手間も増やしてしまうかもしれない。 どんなプログラマにも、「断続的な欠陥」と言ってやれば落ち込むさまを見てとれるだろう。単純な一連のアクションの実行により故障が現れるなら問題は簡単だ。綿密に監視された試験状況のもとで、これらのアクションを繰り返せば、プログラマは何が起こるかを素晴らしく細部まで見ることができる。単純にその方法ではうまくいかない問題はたくさんある。一週間に一度失敗するプログラムや、非常な長期間に一度失敗するプログラムや、プログラマの目の前でやってみせると失敗しないのに、締切が近付くと常に失敗するプログラムなどがあるだろう。 ほとんどの断続的な欠陥は真に断続的ではない。それらのほとんどはどこかに何らかのロジックがある。マシンのメモリが足りなくなると起こるものや、別のプログラムが重要なファイルを誤った瞬間に変更しようとするときに起こるもの、毎時三十分にのみ起こるもの！（私は実際にこれらの全てに出会った） あなたにはそのバグを再現できるのにプログラマは再現できないのなら、彼らのコンピュータとあなたのコンピュータのどこかが異なっていて、この差異が問題の原因であることが多い。かつて、ウィンドウが巻き上がってスクリーン左上に小さなボールとなってそこに居座ってしまうプログラムがあった。しかしそれは８００×６００のスクリーン上でのみ起こり、私の１０２４×７６８のモニタの上では問題なかった。 プログラマはそんな問題について、あなたが見出したことを何でも知りたがるだろう。できるなら別のマシンで試そう。二回三回試して、どのくらい多くしくじるか見よう。重大な仕事をしているときにはおかしくなるのに、実際にやって見せようとするとおかしくならないのなら、長時間の稼働か大きなファイルが関係しているのかもしれない。つまずいた時に何をしていたかできるかぎり詳細に覚えておくようにしよう。何らかのパターンに気が付いたら、それに言及すること。あなたの提供するものはどんなものでも何らかの役には立つだろう。ただ確率的なものであったとしても（「Ｅｍａｃｓが走っているときにより多くクラッシュするようだ」とか）、直接の手がかりは提供しないかもしれないが、プログラマが再現させる役に立つかもしれない。 最も重要なのは、プログラマは真に断続的な欠陥なのか、特定のマシンで起こる欠陥なのかを確実なものにしたがるだろうということだ。区別できるまで、彼らはあなたのコンピュータの詳細をたくさん知りたがるだろう。これらたくさんの詳細は特定のプログラムに依存するが、バージョン番号を提示することだけは肝に命じておこう。プログラム自身のバージョン番号とオペレーティングシステムのバージョン番号、そして大抵は問題に関連する他のどんなプログラムのバージョン番号も。 バグ報告の本質は明確に書くことである。あなたの意味するところをプログラマが分からないのなら、あなたもまた何も言わなかったのかもしれないのだ。 私は世界中からバグ報告を貰う。それらの多くは非英語圏からもので、下手な英語を詫びている。まさかと思うかもしれないが、下手な英語を詫びているバグ報告はおしなべて明快で有用だ。不明解な報告のほとんど全ては英語圏からのもので、たとえ明確にする努力をしなくても理解してもらえるだろうと仮定している。 はっきりしよう。二つの異なった方法で同じことができるのなら、どちらを用いたのか述べよう。「ロードを選択しました」は「ロードをクリックしました」または「Ａｌｔ−Ｌを押しました」を意味する。どちらをやったのか言おう。しばしばそれが問題となる。 冗長になろう。少ないよりも多くの情報を与えよう。言いすぎたら、プログラマはそのうちいくらかを無視できる。ほんの少ししか言わなかったら、彼らは多くの質問を浴びせねばならない。私が受け取ったバグ報告の中には一文だけのものがあった。より多くの情報をお願いしても、その報告者は毎回別の一文を返信してきた。一度にひとつの短い文が明らかになるだけなので、十分な量の有用な情報を得るまでに数週間を要した。 代名詞に気を付けよう。 それが何を意味するか不明確なときには、「それ」のような単語や、「そのウィンドウ」のような参照を使わないように。「ＦｏｏＡｐｐを起動したら警告ウィンドウが現れました。それを閉じようとするとクラッシュしました」という文を考えよう。これでは利用者が何を閉じようとしたのか明らかではない。警告ウィンドウを閉じたのか、ＦｏｏＡｐｐ全体を閉じたのか？これは重要である。代わりに「ＦｏｏＡｐｐを起動したら警告ウィンドウが現れました。警告ウィンドウを閉じようとしたら、ＦｏｏＡｐｐがクラッシュしました」と言うことができる。長くて繰り返しが多いが、より明快で誤解の余地が少ない。 推敲しよう。報告を自分自身で読み返し、明快と思えるかどうか調べよう。一連のアクションを列挙したのなら、それにより故障が起こるはずだ。自分自身でそれに従ってみて、段階を飛ばしていないか調べよう。 バグ報告の第一のねらいはプログラマに自分の目で故障を分からせることである。彼らのところに行って失敗するところを見せることができないなら、彼ら自身で失敗させることができるような詳細な指示書を与えよう。 第一のねらいがうまくいかなくて、プログラマ自身では失敗が確認できなかったら、バグ報告の次なるねらいは何がおかしくなるのかを記述することだ。全てを詳細に記述しよう。何を見たのか、どうなるべきだと思うのか述べよう。エラーメッセージを書き留めよう。特に数字が含まれているものは。 コンピュータが予期せぬ事態に陥ったら、じっとしていよう。落ち着くまで何もしないで。危険かもしれないと思うことはしてはならない。 自分でできると思ったら、どうにかして診断しよう。しかし、そうするならこれまでどおり症状も一緒に報告すべきだ。 プログラマが必要とするなら、すぐに追加の情報を提供しよう。もし仮に必要がなかったとしたら頼まないだろう。わざと不器用に振る舞っているわけではない。手元のバージョン番号はおそらく必要だろうから教えよう。 |
レイクのサイトです。
