効果的にバグを報告するには

作者：Simon Tatham, 職業プログラマ兼、フリーソフトウェアのプログラマ

おおやけに利用されるソフトウェアを書いたことがある人なら、おそらく一通は質の悪いバグ報告を受け取ったことがあるだろう。何も言わんとしない報告 (「動きません!」)、意味をなさない報告、十分な情報を供さない報告、 誤った情報を含む報告などだ。なかには、使用法の誤り、他のプログラムの欠陥、ネットワークの障害などに起因する問題の報告まである。

技術サポートがぞっとする仕事とみなされるには理由があり、その理由こそが質の悪いバグ報告だ。しかしながら、バグ報告は不快なものばかりではない。私は食いぶちを稼ぐのとは別にフリーソフトウェアを保守しているが、しばしば素晴しく明快で有益な、情報量の多いバグ報告を受け取ることがある。

このエッセイでは、どうすれば良いバグ報告ができるのかはっきり述べようと思う。理想的には、バグ報告をする前に、世界中の全ての人にこのエッセイを読んでもらいたい。もちろん、私にバグを報告する全ての人に読んでもらえたら。

端的に言えば、バグ報告の目的は、プログラマ自身が、プログラムが失敗するところを目視できるようにすることだ。じかに見せてもいいし、プログラムを失敗させるための丁寧で詳細な指示書を与えても良い。彼らがプログラムを失敗させることができたら、原因が分かるまでプログラマは追加の情報を集めようし、できなかったら、追加の情報を集めてくれるようあなたに頼むはめになるかもしれない。

バグ報告では、現実に起こったこと（「コンピュータに向かっていたらこんなことが起こりました」）と憶測（「この問題はこうだと思う」）とを明確にするよう心掛けよう。憶測は省きたいなら省いてもいいが、事実を省いてはならない。

あなたはバグが修正されることを望んでいるからバグを報告をするのであって、プログラマを罵ったり、わざと不親切にするのは意味がない。バグはあなたにとって問題で、彼らの落度かもしれないから、あなたが彼らに怒るのも道理かもしれないが、彼らの必要とする情報を全て与えて協力すれば、バグはそれだけ早く修正されるだろう。また、プログラムがフリーなら、作者は親切心からそれを提供しているのであり、あまりにも多くの人々が彼らに失礼な態度を取れば、彼らはその親切心をなくしてしまうかもしれないことを心に留めておこう。

プログラマには基本的な知恵が備わっていると信じよう。そのプログラムが本当に全く動かないのなら、彼らはおそらく気付いているだろうし、気付いていないのなら、彼らのところでは動いているに違いない。従って、あなたが何か彼らと異なったことをしているか、あなたの環境が彼らのものと異なっている。彼らは情報を欲しがっていて、この情報を提供することがバグ報告の目的である。つねに情報は多ければ多いほどいい。

多くのプログラム、特にフリーのものは、既知のバグの一覧を公開している。もし既知のバグの一覧を見付けることができたなら、あなたがちょうど見付けたバグが既知のものかどうかを調べるために読む価値がある。もし既知のものなら、おそらく改めて報告する価値はない。しかし、もし既存のバグ報告より多くの情報を持っていると思うのなら、ともかくプログラマに連絡をしたほうがいい。彼らが知らない情報を与えることができたら、彼らはもっと簡単にバグを修正できるだろう。

このエッセイにはガイドラインがいっぱいだ。どれも絶対的な規則ではないが。特定のやり方でのバグ報告を望むプログラマもいる。プログラムにバグ報告のガイドラインが付属していたら、それを読もう。もしプログラムに付属のガイドラインと、このエッセイのガイドラインが矛盾するのなら、プログラムに付いてきたほうに従おう！

バグを報告しているのではなくて、単にプログラムを使う上でのヘルプを求めているのなら、あなたの疑問に対する答えをどこに探そうとしたのかを示そう（「４章の５．２節の中を参照しましたが、これが可能かどうか示すものは見当たりませんでした」）。これにより、プログラマは人々が答えを期待する場所を知り、文書をより使い易くすることができる。

バグを報告する最良やり方のひとつは、プログラマに見せることである。彼らをあなたのコンピュータの前に立たせ、ソフトウェアを起動して、うまく動かないところを実地で説明して見せよう。マシンを立ち上げるのを見せ、ソフトウェアを起動するのを見せ、ソフトウェアと戯れるさまを見せ、あなたの入力に対してソフトウェアがどう反応するかを見せよう。

プログラマはソフトウェアを隅々まで熟知している。彼らはどの部分が信頼できるか、どの部分に欠陥がありそうか知っている。彼らは直感的に、何を見ればいいか知っている。ソフトウェアが明らかにうまく動かなくなるまでに、彼らは手がかりとなる、先行する微妙な不具合に気付くだろう。この試運転の間にコンピュータがするすべてを観測し、彼らにとって重要な情報を拾い上げることができる。

これだけでは不十分で、彼らはより多くの情報が必要だと判断し、もう一度同じことを見せるよう頼むかもしれない。またバグを彼ら自身で何度でも再現できるよう、ひととおりの手順の説明を求められるかもしれない。手順の変種をいくつか試して、ある単一のケースで問題が起こるのか、一群の関連した場合に起こるのかを調べることもある。運が悪ければ、彼らは開発道具と共に二時間座り込んで本当に調査をしだす必要があるかもしれない。しかし、ここで一番重要なのは、コンピュータがおかしくなったときに、プログラマに見せることである。ひとたび問題が起こるのを確認できれば、彼らは通常、そこから問題を見出し、修正しようとし始めるだろう。

近年はインターネットの時代であり、世界規模のコミュニケーションの時代だ。今日では、ボタンひとつで自分のソフトウェアをロシアのだれかに送り、送られたほうではソフトウェアに対するコメントを私に同じように簡単に送ることができる。しかし、もし彼が私のプログラムに問題をみつけたら、彼は私の目の前でプログラムが失敗するところを見せることができない。「見せて」もらえればいいが、見せることができない場面もよくある。

じかに会えないプログラマにバグを報告するはめになったら、この場合の目的は、彼らに問題を再現可能にしてあげることだ。プログラマにプログラムのコピーを起動してもらい、あなたと同じことをしてもらい、同じように失敗させよう。彼らも問題を目の前で確認できれば対処できる。

だからあなたがしたことを正確に彼らに伝えよう。グラフィカルなプログラムなら、どのボタンをどんな順序で押したのかを伝えよう。コマンドをタイプして走るプログラムなら、タイプしたコマンドを正確に教えよう。可能ならどんな場合でも、あなたがタイプしたコマンドと、それに対するコンピュータの応答出力からなるセッションの完全な複製を提供しよう。

プログラマには、あなたが考えうる全ての入力を与えよう。プログラムがファイルを読むなら、おそらくそのファイルの複製を送る必要があるだろう。プログラムが別のコンピュータとネットワーク越しに通信するなら、そのコンピュータの複製は送れなくても、少なくともそれがどんな種類のコンピュータかを言うことができるし、（できるなら）その上で動いているソフトウェアが何か言うことができる。

あなたがプログラマに入力とアクションの長いリストを与えて、彼らが手元でそのプログラムを起動しても何もおかしなことが起きなければ、与えた情報が不十分だったということだ。多分その欠陥が全てのコンピュータでは顕在しなくて、あなたのシステムと彼らのシステムのどこかが異なるか、あるいは多分あなたがそのプログラムの挙動を誤解していて、まったく同じ表示を見ていても、あなたはおかしいと感じ、彼らはそれが正しいと理解している。

だから何が起こったのかも述べよう。見たことを正確に、どうしてそれがおかしいと思うのかを伝えよう。どうなるべきだと思うのかを伝えればさらにいい。「～したらおかしくなりました」と言うだけでは、とても重大な情報をいくらか省いたことになる。

エラーメッセージを見たら、それがどんなものだったのか丁寧に正確にプログラマに伝えよう。エラーメッセージは重要だ！この段階では、プログラマは問題を修正しようとはしていない。ただそれを見つけようとしているだけだ。彼らは何がおかしくなっているのか知る必要があり、エラーメッセージは、それをコンピュータがあなたに伝える最大限の努力だ。エラーメッセージを覚えておく簡単なやり方がないなら、エラーを書きとめよう。エラーメッセージがどんなものだったのかを報告できないのなら、プログラムがエラーを起こしたと報告しても意味はない。

特に、エラーメッセージに数字が含まれるなら、プログラマにそれらの数字を提供しよう。あなたには意味が見出せないからといって、それはそこに何の意味もないというわけではないのだから。数字にはプログラマが読みうるあらゆる種類の情報が含まれていて、それらはえてしてきわめて重大な手がかりとなる。エラーメッセージに数字が含まれるのは、コンピュータが混乱しすぎてエラーを単語で報告できないためにある。しかしコンピュータはベストを尽くし、重要な情報をなんとか伝えようとしているのである。

この段階では、プログラマは手際良く探偵仕事をしている。彼らは何が起こったのか知らないし、彼ら自身のもとでその問題が起こるのを目視できるほどには突き詰めることができていない。で、問題を取り除く手掛かりを探している。エラーメッセージ、不可解な数字の羅列、説明のつかない遅延でさえ、全ては殺人のシーンの指紋と同じくらい重要だ。それらを捨てないように！

Ｕｎｉｘを使っているなら、プログラムはコアダンプするかもしれない。コアダンプは特に良い手がかりの源泉なので捨てないで。とは言うものの、ほとんどのプログラマは巨大なコアファイルを警告なしに電子メールで受け取るのを嫌うので、誰かに送る前には尋ねよう。また、コアファイルにはプログラムの完全な状態が記録されていることに気を付けよう。どんな附随する「秘密」が含まれているとも限らないのだから（たぶんプログラムが個人のメッセージを扱ったり、機密のデータを処理したりして）。

エラーやバグが起きたときに、やってしまいがちなことは沢山ある。それらの多くは問題を悪化させる。学校の私の友達は、Ｗｏｒｄの文書を誤って全部消してしまった。そして専門家に助けを呼ぶ前に、彼女はＷｏｒｄを再インストールし、Ｄｅｆｒａｇを試みた。これらはどちらも彼女のファイルを復元する役には立たず、その間に、これらの操作によって彼女のディスクは世界中のどんな消去取消プログラムでも一切修復できないほどにごちゃまぜになった。彼女がそのままにしていたらチャンスはあったかもしれないのに。

このような利用者は角に追い詰められたマングースに似ていて、何もしないよりは何かしたほうがましに違いないと、背水の陣でやみくもに攻撃する。これはコンピュータの生み出すタイプの問題ではうまくいかない。

マングースになるかわりにカモシカになろう。カモシカは予期せぬ物事や驚くべき物事に直面すると、じっと動かなくなる。完全に静止し、他の動物の注意を引かないよう試みる。そのあいだに、止まり、考え、いちばんすべきことを見極める(もしカモシカが技術サポートにつながる回線を持っていたなら、この時点で電話をかけることだろう）。そして、いったん一番安全な行動を決定したら、実行する。

何かがおかしくなったら、ただちに何をするのもやめよう。どのボタンにも一切触れないように。スクリーンを見て、不自然なものに全てに注意を払い、覚えるか書きとめよう。それから、場合によっては、はじめて「ＯＫ」か「キャンセル」どちらでもいちばん安全なほうを注意深く押そう。条件反射を身に付けよう−−コンピュータが予期せぬことを始めたら、じっと動かないように。

影響を受けたプログラムを閉じたり、コンピュータを再起動したりして、問題からなんとか逃れたら、もう一度それを起こそうとしてみるのが良い。プログラマは一回以上再現可能な問題を好む。ハッピーなプログラマはより早く、より効果的にバグを修正する。

質の悪いバグ報告を生むのは非プログラマだけではない。私が見てきた中で最悪のバグ報告のいくつかは、プログラマから寄せられたものだ。その中には良いプログラマさえいる。

かつて私は別のプログラマと仕事をしていた。彼は自分で書いたコードにバグを見つけては修正していた。彼は解決できないバグに出会うたびに、頻繁に、私のところに立ち寄って助けを求めた。「どこがおかしくなったの？」と私が尋ねると、返事のかわりに、修正するために何が必要か、彼の現在の意見を述べられた。

彼の現在の意見が正しいときには、これはうまくいった。それは彼が既に仕事の半分を済ませていて、我々は一緒に仕事を完了できることを意味していた。効果的で有用だった。

しかしきわめて頻繁に彼は間違っていた。私達は、プログラムのある特定の部分がなぜ不正なデータを生み出しているのかを解明しようと時間を費し、やがてそうではないことに気付いた。本当の問題は他の部分にあるのに、完全にまともなコードを30分調査していたことになる。

きっと彼は医者に対してはそんなふうに振る舞わないだろう。「先生、ハイドロヨーヨーダインの処方箋を出してください」とか。人々はそんなことを医者に言うべきではないと知っているから、現実の不快感やうずき、痛み、発疹、熱といった症状を訴えて、問題が何なのか、それについてどうするべきなのか医者に診断してもらう。さもなくば医者はあなたを心気症か風変わりな人だと追い払うに違いない、まあ実際そうなのだろうが。

これはプログラマに対しても同じだ。あなた自身による診断もたまには役に立つが、いつでも症状を述べるようにしよう。診断は任意の余分なものであって、症状を伝える代わりにはならない。同様に、バグ報告に添えて、問題を修正するコード上の変更を送るのは有用だが、バグ報告の代用としては十分ではない。

プログラマがあなたに追加の情報を求めてきたら、それを捏造しないように！かつて私にバグを報告してきた人に、動かないことが分かっているコマンドを試してくれるよう頼んだことがある。試してくれるよう彼に頼んだ理由は、それにより得られる二つの異なったエラーメッセージを知りたかったからだ。どんなエラーが返ってくるかを知るのは、きわめて重大な手がかりとなる。しかし彼は、実際には試さずに、「いいえ、それは動かないでしょう」というメールを返してきた。実際に試すよう彼を説得するのにしばらく時間がかかった。

プログラマに役立つために、知性を使うのは立派だ。たとえ推論が間違っていたとしても、プログラマはあなたが何はともあれ手間を省こうとしてくれたことに感謝するはずだ。けれども、同様に症状を報告しよう。さもなくば逆に手間も増やしてしまうかもしれない。

どんなプログラマにも「断続的な欠陥」と言えば、落ち込むさまを見てとれる。簡単な問題とは、単純な一連のアクションを実行することで故障が現れるたぐいのものだ。プログラマは、そのアクションを繰り返し、じっくりテストの条件を観察すれば、何が起きているのか、ごく細部まで見ることができる。多くの問題がそんなに単純にはいかない。一週間に一度だけ失敗するプログラム、ごくまれに失敗するプログラム、プログラマの目の前でやってみせると失敗しないのに、締切が近付くと常に失敗するプログラムなどがあるだろう。

断続的な欠陥のほとんどは真に断続的ではない。それらのほとんどはどこかに何らかのロジックがある。マシンのメモリが足りなくなると起こるものや、別のプログラムが重要なファイルを誤ったタイミングで変更しようとするときに起こるもの、毎時三十分にのみ起こるもの！（私は実際にこれらのうち一つに出会ったことがある）

また、あなたにはそのバグを再現できるのにプログラマは再現できないのなら、明らかに彼らのコンピュータとあなたのコンピュータのどこかが異なっていて、この差異が問題の原因である。かつて私のところに、ウィンドウが縮こまって小さなボールとなりスクリーン左上に居座り、無反応になるプログラムがあった。しかしそれは８００×６００のスクリーン上でのみ起こり、１０２４×７６８のモニタの上では問題なかった。

プログラマは問題について、あなたが探り当てたことを何でも知りたがるだろう。できたら別のマシンで試そう。二回三回試して、どのくらい多くしくじるか見よう。仕事に使っているときにはおかしくなるのに、問題を実地で見せようとするとおかしくならないのなら、長時間稼働させたり、大きなファイルを扱うと、つまずくのかもしれない。プログラムがつまずいた時に何をしていたかできるだけ詳細に覚えておくようにしよう。何らかのパターンに気が付いたら、それにも言及すること。あなたの提供するものはどんなものでも何らかの役には立つだろう。ただ確率的なものであったとしても（「Ｅｍａｃｓが走っているときにより多くクラッシュするようだ」とか）、直接の手がかりは提供しないかもしれないが、プログラマがその問題を再現させる役に立つかもしれない。

最も重要なことには、プログラマは、扱っているのが真に断続的な欠陥か、特定のマシンで起こる欠陥なのかを確認したがるだろう。彼らのコンピュータとあなたのコンピュータがどれだけ異なるのかを解明するために、彼らはあなたのコンピュータの詳細をたくさん知りたがるだろう。これらの詳細の多くはその特定のプログラムに依存するが、何をおいても進んで提供すべきはバージョン番号だ。プログラム自身のバージョン番号とオペレーティングシステムのバージョン番号、そしておそらく問題に関与する他のすべてのプログラムのバージョン番号も。

バグ報告の本質は明確に書くことである。あなたの意図するところをプログラマが分からないのなら、何も言わないのと同じだ。

私は世界中からバグ報告を貰う。それらの多くは英語を母語としない話者からもので、下手な英語を詫びている。下手な英語を詫びているバグ報告はおしなべて明快で有用だ。不明解な報告のほとんど全ては、たとえ簡潔または正確にする努力をしなくても私が理解するだろうと仮定しているネイティブの話者からのものだ。

免責: 実際には私はマングースやカモシカを見たことがない。私の動物学は不正確かも知れない。

この記事は特定のプログラムのために書かれたものではありません。

ある特定のプログラムのウェブサイトからのリンクを辿りこのページに訪れたのなら、そのプログラムのバグ報告を私に送らないでください。かわりに元来たページに戻り、そのプログラムのバグをどこに報告したら良いか調べてください。

この記事そのものについてもしコメントや批判があれば、anakin@pobox.comまでお送りください。

効果的にバグを報告するには

はじめに

「動きません」

「見せてみて」

「どうやって見せればいいか教えて」

「うちでは動くけど何が問題なの？」

「なのでその後…を試したけど」

「思うに、タキオン変調の極性が反転しているに違いありません」

「おかしい。ちょっと前までは動いたのに」

「そこで、Ｗｉｎｄｏｗｓにディスクをロードしました…」

まとめ