バグを報告するとき気をつけてほしいこと

レビューなどを眺めていると、バグを伝えたい、という気持ちはうかがえるものの、正確にそれを伝えられていないために、改善につながらない報告があふれかえっています。（おそらく当人は大真面目なのでしょうが）
仕事として評価を行っている人の場合でも、たとえ本職のエンジニアであっても、バグを正確に報告するというのは意外なほど難しいものです。

例えば、私はかつてこんな報告を受けたことがあります。

> **インターネットにつながらない**

一般ユーザーからの連絡ではありません。仕事で評価を行っている人からのバグ報告です。
誇張でも抜粋でもありません。テンプレートに従って評価したソフトバージョンなどはついていましたが、症状については本当にこの一文のみの報告でした。

この報告で一体何が伝わるでしょうか？頑張って伝えたいことを推測したところで、

> **この人はインターネットに接続するための、もしくは接続を前提としている**
> **（と、この人が推測している）何かの機能を使おうとしたのだろう**
> **そこでその人がインターネットにつながらないと推測するに足る、何かの現象が起こった**
> **もしくは、インターネットに接続していれば発生すると推測している何かが起こらなかった**

ぐらいでしょうか？
どのような状態で、どのような結果になることを期待して、何をして、何が起こったのか（起こらなかったのか）が何一つ分かりません。

せっかく報告するのだから、きちんと伝わらない、意味のないものになってしまってはもったいないです。
そうならないために、どういうところに気をつければいいかなど具体例を挙げながら説明してみたいと思います。
具体例を挙げる場合は通信を使用するアプリ（ソフトウェア）を前提としていますが、言葉を換えればどの業界でも通用することだと思います。

まあ、もう書いてしまっていますが、前提情報のない報告を受ける側の立場になって
**「どのような状態で」「どのような結果になることを期待して」「何をして」「何が起こったのか（起こらなかったのか）」**
をできる限り正確に伝えることが重要です。

# 推測した原因を報告しない/起こった事実を正確に伝える

やってしまいがちですが、原因究明につながらない報告の筆頭です。
推測した原因を報告するのはやめましょう。どうしても伝えたいのであれば、推測であることを明記した上で報告しましょう。

最初に出した例

> **インターネットにつながらない**

も、これに当たりますね。インターネットにつながらない、という現象が目に見えて起こるということは通常ないと思います。

例えば、ちょっと意地悪ですが、「インターネットに接続していません」というエラーメッセージが表示されたとしても、その場合、報告すべき事実は

> **「インターネットに接続していません」というエラーメッセージが表示された**

です。

原因はインターネットへの接続に何らかの問題が発生したという可能性は高いですが、このエラーメッセージの表示条件が間違っている可能性もありますよね？「インターネットにつながらない」という事象が直接観測されたわけではないはずです。

報告を受けた側は、このように報告するということは、おそらくこういう事象が発生した（発生しなかった）からだろう。
と、推測の原因から発生した事実を推測するところから始めなければなりません。推測の推測になるのでそれが合っている保証も何もない状態で調査をしなければならないのです。
どれだけ不毛な作業が発生するか想像つきますでしょうか？

原因は分かりきっている。ここがおかしいんだよ。と、完全に疑いの余地もなく原因が推測できる場合もあるでしょう。
その場合であっても

> **○○という現象がおこった、○○を調べてみたところ○○で、○○については○○だった、つまり○○に○○というバグがあると推測します**

と先に事実を正確に書き、推測であることを明確にした上でなぜそのように推測するのかを含めて報告しましょう。
とはいえ、それでもあなたの推測は報告を受けた側を混乱させる、ただのノイズ扱いされる可能性が高いです。つまりバグ報告に含められる推測原因は、報告者の自己満足以外の役にはたたない場合がほとんどと心得ましょう。

# 用語を使って正確に伝えた気にならない

> **～～という手順で操作したとき、フリーズした**

カッコいい！短い文章で手順と現象を表現しようとしています。

・・・さて、フリーズってなんでしょう？

操作を受け付けない状態？操作を受け付けないのはどの操作ですか？存在するすべての操作を試したわけはないですよね？マウスは？キーボードは？タッチパネルは？ボリュームは？電源ボタンは？
そのとき画面の表示はどうなっていました？操作する前の状態で止まっていた？操作のフィードバックはあるけどその後の動くべき機能が動かない？表示に乱れがあったりしたでしょうか？ひょっとしたら画面は真っ黒でした？
音を出す機能がある場合、音はどうでしょう？画面表示が止まっていても音だけは出ている場合とかもあり得ますね。
LEDがあるならLEDはどんな状態でした？
あ、ひょっとしたら、操作を受け付けないのではなく、すごく遅い状態をフリーズと表現する人もいるかもしれませんね。その場合はまた別のことを調べないといけないですね。

用語は便利ですが、本当にそれですべてを伝えられるかというとちょっと違います。むしろ推測の原因に近いですね。
用語を使うとその周囲の情報まで合わせて報告できた気になってしまうので注意しましょう。
また、間違って使う人が多い用語を使うと、仮にあなたが正しい意味で使っていても受け取った側には分かりません。正しい使い方であっても複数の意味がある用語などもそうですね。
受け取った側は結局想定される意図すべてを調べる羽目になります。

誤解を生まないためにも、正確に伝わるように受ける側の立場になって報告しましょう。これはこういう意味だよ。と２重３重に説明してもいいのです。
くどくなる？誤解を生むよりもよっぽどいいです。
カッコ悪い？カッコ悪いと思うその考えがカッコ悪いです。
字数制限がある？・・・頑張れ！

言葉を尽くして正確に！

# 自分の環境を説明する

基本中の基本ですが、自分の当たり前に使っている環境については、伝える必要もなく当たり前に分かってもらえるものと思ってしまうところがあるのでしょうか？
これが伝えられていない人は多い。

これは人間に依存せず機械的な補助で大きく改善できるところなので、報告を受ける側が自動的に情報を収集してそれを添付するような仕組みを作るのが第一ではありますが、そこで集めきれない情報ももちろんあるので、
報告を行う場合は可能な限り明確になるように説明するようにしましょう。

- 問題が起こったソフトウェアのバージョン
- ソフトウェアの設定
- 発生日時
- 使用している端末の種別、OSバージョンなどのハードウェア/ソフトウェア情報
- 端末の通信接続状態、3G/4G/WiFi/有線など
    - LANの場合はその構成やルーターの種別なども必要かもしれません

もちろん、内情も分からない状態で、必要な環境情報をすべて列挙するなどということは不可能でしょう。ですが思いつく限りの情報は伝えるようにしましょう。

# 機能名、ボタン名などはその環境内での表現に合わせる

報告する際、「○○の画面で」などと表現する際、その名前はあなたがそう思っているだけの名前になっていないでしょうか？

例えば、ブラウザなどには「ブックマーク」という機能がありますが、同様の機能で「お気に入り」と表現しているものもありますよね。これだけならどちらで書かれても推測することはできますが、例えば「ブックマーク」の他に「お気に入り」という機能も別にあった場合に、「ブックマーク」とそのソフトウェア内で表現している機能を「お気に入り」と表現してしまったら・・・正しく伝わらず、混乱することは明らかですよね。

「「お気に入り」なんてないし、わかるでしょ」いやいや、あなたが知らないだけかもしれませんよ。もしかしたら、かつて存在していたが今は存在しないというものかもしれません。

きちんと相手に伝えるためにも表現を合わせましょう。

「なんか表記ゆれがあってどの名前が正しいのかわからんわ」
うん、まれによくある。それ自体もうバグみたいなもんだからそれはそれで伝えましょ。

# 表示されたエラーメッセージ、エラーコードなどを正確に伝える

なぜでしょうか、最も簡単かつ正確に報告できる手段であるはずの、エラーメッセージやエラーコードを頑なに伝えようとしない人がいます。私には理解できないのですが、そのような人が非常に多いことは確かです。

> **メニューボタンを押したら、エラーメッセージが表示された**

・・・そのエラーメッセージの中身が重要なんだよ！なんでそれを書かないんだ！！

読み取れないほど一瞬しか表示されないとか、一度しか発生していないので覚えられなかった、など、仕方ない場合もあるでしょう。
ですが、読み取れるのであれば、何が発生しているのか、この上なく正確に伝えることができる手段なので、絶対に正確に伝えるようにしましょう。

また、メッセージの他にエラーコード、（多くの場合、直接意味を読みとることができない英数字の羅列）を一緒に表示している場合もあるかもしれません。
メッセージよりもさらに正確な情報源ですので、的確に伝えるようにしましょう。

# 行った操作を正確に伝える。可能なら再現手順の確立を

> **この画面のこのボタンを押したら、エラーメッセージが表示された**

その画面を表示する方法はたくさんあるんですが、どうやって表示させました？
問題が発生した目の前の情報というのはちゃんと書けてもその前の状態は何かまで説明するのは難しいものですが、そこが重要だったりします。
報告を受ける人はあなたのそばでその操作を見てくれていた人ではありません。何も知らない人に自分がやったのと同じ操作をしてもらうには何を伝えればいいのかをよく考えて報告しましょう。

可能であれば、この手順で操作を行えば発生させることができる、という再現手順を明確にした上で報告しましょう。
分からないなら分からないと報告しましょう。再現手順を問い合わせる手間が減ります。

# 意味のない曖昧な条件情報を付与しない

怒りにまかせたレビューとかでたまにありますね。仕事の報告でこんな表現をする人はいないと信じたいけどたまにいます。

> **どのファイル開いてもいつもクラッシュする、全部だよ全部！他のユーザもみんな同じだっていってる！**

あなたはこの世に存在するすべてのファイルについて、例外なくすべて検証し、同一の現象が発生すると確認したということでしょうか？そんなわけないですよね？
他のユーザ全部、本当に世界中のユーザすべてに聞いてみたんですか？せいぜいあなたの知り合い数人で、しかも使っている端末やファイルは偏ってたりするんじゃないでしょうか？

この手の説明で、全部、常に、いつでも、みんな、などという説明は意味がありません。少なくとも受け手は文字通りには受け取りません。
本当にすべてのパターンを網羅した検証を行った場合であっても、曖昧な言葉を使わず、正確に説明すべきです。

全部、常に、いつでも、みんな、と説明しても、せいぜい、再現性のあるバグなんだろうな、ぐらいしか伝わりません。
再現性の高さを伝えたいなら次項です。

# 再現性・発生頻度を正確に伝える

バグの対応では再現性は非常に重要です。
仕事での報告の場合、この報告が義務づけられてたりしますが、いい加減な情報だとかえって混乱してしまいます。

> **再生ボタンを押したらクラッシュした、再現率100%**

・・・うーん、同じ操作を何回しても問題は起こらないな。
で、詳細を聞いてみたら、1回操作して1回クラッシュしたから100%と報告しました。

・・・おかしいよね？それは1回のみ発生であって、一度たりとも再現していないでしょ？再現率0%ですよ？

確率で報告するなら最低でも複数回再現させてください、できれば確率ではなくて単に何回施行して何回再現したかだけを報告してください。

> **再現率10％（最初の1回のみ発生、9回やり直して発生しなかった）**

違う！これも「再現性なし」！一度も再現できていない！表現は正確に！

> **再現率10%、下記の手順で100回操作を行い、10回再現**

そのぐらいやってくれたなら確率で書いてもいいでしょう。でも確率より後半の試行回数と再現回数の方が重要ですからね。

# どうなることを期待したのか

事実を正確に伝えるに通じますが、想定した動作が起こらなかったと報告する場合は特に、どうなるべきだと考えていたのかを伝える必要があります。
正確に現象や前提条件を説明できても、忘れてしまいがちです。

> **＋ボタンを押したらボリュームが大きくなった**

えーと、仕様通りなんだけど？で終わってしまいます。

> **カーソルを上に動かそうと、＋ボタンを押したらボリュームが大きくなった**

と説明してくれれば、仕様通りの動作だったとしても、何か勘違いさせるようなデザインや説明などになっているのではないか？と調べ始めることができます。

# その他

可能ならスクリーンショット（写真）や動画なども添付するとよいでしょう。
百聞は一見にしかず。言葉では説明しきれない情報を正確に伝えることができます。
動作ログなどをとる方法を知っている場合はそれをとって送るのも非常によいでしょう。

# まとめ

ざっと、バグ報告のときに気をつけてほしいことを書きました。
バグ報告に限りませんが、あなたの事情は相手は何も分からない、その状態で相手の立場で理解してもらえるか？と気をつけながら説明することが重要です。
かくいう私もできている自信はありませんが、せっかく報告するのです、すこしでも改善につながる意味のある報告をしたいものです。