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

投稿者: | 2014年6月25日

はじめに

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

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

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

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

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

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

 

「動きません」

 

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

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

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

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

 

「見せてみて」

 

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

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

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

 

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

 

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

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

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

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

 

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

 

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

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

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

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

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

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

 

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

 

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

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

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

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

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

 

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

 

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

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

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

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

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

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

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

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

 

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

 

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

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

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

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

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

 

「そこで、Windowsにディスクをロードしました…」

 

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

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

  • 具体的に述べよう。 同じことが、二つの異なった方法でできるなら、 どちらを用いたのか述べよう。「『ロード』を選択しました」は「『ロード』 をクリックしました」または「Alt-Lを押しました」を意味する。どちら をやったのか言おう。しばしばそれが問題となる。
  • 冗長に述べよう。 なるべく多くの情報を与えよう。言いすぎてもプ ログラマは気にしない。あまりにも何も言わなかったら、彼らは返信してより 多くの質問をしなければならない。私が受け取ったバグ報告の中には一文だけ のものがあった。より多くの情報をお願いしても、その報告者は毎回別の一文 を返信してきた。一度にひとつの短い文が明らかになるだけなので、十分な量 の有用な情報を得るまでに数週間を要した。
  • 代名詞に気を付けよう。 「それ」のような単語や、「そのウィンド ウ」のような参照は、意味が不明瞭な時には使わないように。「FooApp を起動したら警告ウィンドウが現れました。それを閉じようとするとクラッシュ しました」という文を考えよう。これでは利用者が何を閉じようとしたのか明 らかではない。警告ウィンドウを閉じたのか、FooApp全体を閉じたの か?これは重要である。代わりに「FooAppを起動したら警告ウィンドウ が現れました。警告ウィンドウを閉じようとしたら、FooAppがクラッシュ しました」と言うことができる。長くて繰り返しが多いが、より明快で誤解の 余地が少ない。
  • 書いたら読み返そう。 報告を自分自身で読み返し、あなたが明快と思えるかどうか確認しよう。一連のアクションを列挙したのなら、それにより故障が起こるはずだ。自分自身でそれに従ってみて、段階を飛ばしていないか調べよう。

 

まとめ

 

  • バグ報告の第一の目的は、プログラマに、彼ら自身の目で失敗を確認してもら うことだ。彼らのところに行って彼らの目の前でプログラムを失敗させられな いなら、彼ら自身でプログラムを失敗させることができるよう、詳細な手順書 を与えよう。
  • 第一の目的がうまくいかなくて、プログラマ自身では失敗が確認できなかっ たら、第二の目的は何がおかしくなったのかを記述することだ。全てを詳 細に記述しよう。何を見たのか、あなたが見ることを期待していたのは何か述 べよう。エラーメッセージを書き留めよう。特に数字が含まれているもの は
  • コンピュータが予期せぬ動作をしたら、じっとしていよう。あなたが 落ち着くまで何もしないで。危険かもしれないと思うことはしてはならない。
  • 自分でできると思ったら、どうにかして診断しよう。しかし、それでも症状も 一緒に報告すべきだ。
  • プログラマが必要とするなら、よろこんで追加の情報を提供しよう。もし仮に 必要がなかったとしたら頼まないだろう。わざと不器用に振る舞っているわけ ではない。おそらく必要なバージョン番号は、すぐに提供できるようにしてお こう。
  • 明快に書こう。あなたの意味するところを言って、誤った解釈をされないよう気をつけよう。
  • 何にもまして正確に。プログラマは正確さを好む。

引用元 
http://www.chiark.greenend.org.uk/~sgtatham/bugs-jp.html

 

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です