バグチケットの書き方

ほんともー呆れた。から記事にしてみよう。

バグチケットっていうのは、あるシステムにバグが見つかったときに、担当者に向けて「これこれこういうバグがあったよ」という報告をするものだ。バグ報告。

例えば、花火大会で発生した事故を想像してみてくれ。

筒に発射火薬を入れ、花火玉をつめ、落とし火を入れた。

そうしたところ、花火が横に射出され、観客席に飛び込んでから爆ぜた。

バグは「筒が横に倒れていた」ことだ。じゃあ、これについてバグチケを起こしてみる。

◆何故に普通のバグチケを書かねばならんのか

コミュニケーションコストを下げるためだ。聞き直す手間を無くすためだ。相手の仕事を無駄に増やしてはいけない。修正にかかる時間を増やしてはいけない。同期的コミュニケーション（つまり会話）は、自分の時間も削られる。結果的に全員が残業することになる。

簡潔に要点が伝わればバグが修正されやすくなる。会話の必要がなくなる。

妙なバグチケを起こしてしまうと、それを読んだ相手の心証を悪くする。信頼が損なわれる。「何言ってんだコイツ」と、無能の烙印を押される。

◆タイトル

まずはタイトル。以下のうち、好ましいタイトルはどれだろうか。

・観客席で花火が爆発した

・花火がおかしい場所に飛んだ

・花火の玉が横に射出された

・花火の筒が横に倒れていた

これで一番上を選んでしまう事はないだろう。と思いたい。

▼観客席で花火が爆発した

それは、連鎖した結果だ。つまり「けが人が出た」「救急車が来た」というバグチケと変わらん。

「花火を発射したら救急車が来た」じゃなんのこっちゃわからん。救急車が来ないようにすればいいのか？じゃあ救急車のタイヤを五寸釘でごっすんしてパンクさせてしまおう。

▼花火がおかしい場所に飛んだ

情報量が足りていなさすぎる。「おかしい場所」ってなんだ。おかしいかどうかはお前の主観だ。おかしいかどうかは、バグであるかどうかと関係がない。おかしいのが正常動作ってこともあり得るからだ。どういうケースかわからんが。

だから、発生したその「おかしい」事象を客観的に表現しろ。

もっと悪いと「花火の発射がおかしい」的なタイトルになる。どうおかしいんだよ。それが許されるんなら、タイトルが「マジ卍」でもアリになるだろ。

タイトルの情報量が足りていないと、別のバグが発生したときにタイトル被りが発生する。「花火の発射がおかしい」だと、例えば「発射するときに筒が爆発した」という不具合も含まれてしまう。

▼花火の玉が横に射出された

わかりやすい。発生した不具合の要点を捉えている。

バグチケを見た人は「花火の玉が横に射出されたんだな。横に射出されるのがまずいから、射出する方向を直せばいいんだな。」ということを理解できる。あとで一覧にしたときも、タイトルでどの話か判断することが出来る。

▼花火の筒が横に倒れていた

惜しい。それは原因。バグチケには必ずしも原因を書く必要はない。書いてもいいし書いてあると助かるけど。

筒が横に倒れていても上に玉が打ちあがるかもしれない。だから「横に玉が発射されている」という不具合を指摘できていない。

あと、見当違いの事を言ってしまう可能性がある。「玉に溝があってそれの空気抵抗でカーブがかかり観客席に飛んだ」とか、調査した結果とんちんかんな結論に至ってしまう可能性がある。バグの原因究明は起票者の仕事ではない。担当者にぶん投げろ。

◆再現手順

そのバグを再現するための手順、状況を書け。再現不能であった時はその限りではない。

これを書かないと、担当者はバグを再現するための手順を探す長い旅に出なければならない。でも結局のところ、バグを発見した人がその再現手順を知っている。二度手間。

再現手順は、ロボットでもわかるように書け。箇条書きで手順を並べろ。その機能を使ったことが無い人に説明するくらいの気概でいけ。

それが出来ないんなら操作の全てを画面キャプチャして持ってこい。

◆環境情報

知り得る限りの環境情報を付加しろ。「Windowsでバグったよ」とか「Chrome 74でバグったよ」とか「iOS 10.3.4でバグったよ」とか。あと、必要だと思うなら日時も付け加えろ。

よくよく話を聞いたらWindows XPで発生したバグだったとか嫌だろ。

◆受け入れ条件

「どのような状態になったらOK」という話を正確に伝えろ。箇条書きでな。文章で書こうとするな。

受け入れ条件の例をみていく。

▼ダメな例

・普通の花火みたいになること

何が普通で何が普通じゃないかなんてわからん。お前が定義して、お前が決めろ。

・下記資料のようになること

範囲が広いわ。絞れ。

仕様の定義は開発者の仕事ではないし、テスト管理も開発者の仕事ではない。開発するのが開発者の仕事である。兼務もありうるけどね。だから、開発者には「ここがおかしいのでこうなれ」という命令をするのが正しい。

お前の納得いかなかった部分が、どうやったら納得いくのかを伝えろ。

▼よい書き方

• 花火が上に発射される事

今回の例だと、これだけでいい。

上に発射されて地上1メートルで爆発しても関係ない。炸裂せずに玉のまま落ちてきても関係ない。それらは別のバグだ。

とにかく「上に飛ばないバグ」と範囲を絞り、上に飛ぶことだけを求めろ。こまかく起票して、ぶん投げるときは纏めてぶん投げろ。

◆おまけ：うごきませんでした

老人か何かかお前は。

例えば「ログインできませんでした」と報告されてもどうしようもない。「そう…」としか言えない。

最低限、どのユーザーでログインしようとしたのか教えてもらわない限り調査ができない。欲を言えば、「いつ」リクエストをかけて、「どういう感じにログインできなかった」のかを教えて頂ければ嬉しいですぅ。HTTPのリクエスト＆レスポンスをいただければ調査しやすいですぅ。

◆結論

ちょっと書ききれてないけど、そんな感じ。

バグ報告っていうのは、開発者がいま取り組んでいる作業に割り込むものだ。だから開発者は殺気立つ。そして、それが高品質なバグ報告であれば心がなごむ。雑なバグ報告は殺意を高めてしまう。

現場に修羅を発生させないためにも、作法にのっとったバグチケを起こせ。