「困った」バグレポートの数々から得た「正しい」レポートのための教訓とは

必要のない情報が多い

バグ修正に必要のない情報の例として下の2つがあります。前のページの「説明が不十分」と組合わさっている場合、記述の分量は十分だけれども、症状が理解できなかったり再現できなかったりすることがあります。分量だけで判断するのではなく、本当に必要な情報が書かれているかで判断しなければなりません。

1. 知識の披露が中心になっている

「Xの原則というのがあり、文献Yでも事例が紹介されています。文献Yは私の経験則にも十分にあてはまる内容で信頼しています。Xの原則にもとづくと「確認」ボタンが二度押しされたときの処理は非常に重要であり、ボタンが押せないようdisableにするか、二度押しのリクエストを受け取っても二度目は無視するといった処理が必要でしょう。」というような記述です。前半はバグ修正には必要ありません。補足事項として書ける欄があるならばそこに記入しましょう。「確認」ボタンが二度押しできたときに起こる問題を述べるほうが優先順位が高いでしょう。

2. テストエンジニアが実行した全手順が記述されている

症状欄に「最初は、正常と思われる入荷量300と予定期日に平日の昼間の時間帯を入力して動作が期待通りであることを確認した。次に入荷量の上限値3999を超える4002を入力し、休日の昼間の時間帯を入力してエラーメッセージが正常に出力されないことに気づいた。そう、上限値を超えています」というような記述です。過程を書くとわかりやすくなることもあるのですが、関係のない部分が多いと理解しづらくなります。再現方法を確認しながら、必要のない部分を削除していきます。

バグを報告するスキルを意識する

問題のある4つのパターンを紹介しました。これらを防ぐための方法を紹介します。冒頭でも書きましたが、バグを検出するスキルと報告するスキルは別のものであることを認識し、報告するスキルも磨きましょう。スキルを磨くために心がけておくことを3つ紹介します。これまでに書いた対策と違って、すぐに効果が出るものではありませんが、長期にわたって取り組むことで大きな効果が得られます。

1. 読み手を意識する

バグレポートを最終的に受け取るのは、プログラマです。テスト部隊の部門長やリーダ、開発部隊の部門長やリーダ等、様々な人の目に触れる可能性がありますが、最終的な受取手であるプログラマを十分に意識することが大切です。プログラマはバグレポートの内容からバグを再現したり、問題部分を推測したりして、バグを修正していきます。そのために十分な情報が書かれているか、不必要な情報はないかということを意識しましょう。

原則は、バグレポートを書く前と書いた後のそれぞれで「このバグレポートはバグ修正に役立つものになっているか？」を自問することです。どのような情報が書かれていないと再現できないか、プログラマはどうやってバグの原因を推測していくかを知り、プログラマがそのバグレポートを受け取ったら、既に持っている知識とどう組合せてバグを修正していくかをシミュレーションします。そのためには、チームや個々のプログラマが何を知っているか（バグレポートに書く必要がないか）、どのような内容は書いておかないと理解できないか（バグレポートに書くべきか）を普段から意識して情報収集しておく必要があります。その情報は、普段の会話の中から得たり、バグレポートのやりとりの中から得たり、開発関係者に聞いたりします。

また、勘違いが起きたり「情報が足りない」という指摘をプログラマから受けたりしたときには、どの部分が足りなかったかを考え、次を防ぐためには何を意識すべきかを考えましょう。前提が誤っていた、プログラマが知っていると思っていたことはないでしょうか。

2. 解決に向けた姿勢を表わす言葉を一言入れよう

チームでソフトウェア開発をしていることを忘れずに。バグが見つかったこと自体は仕方がないことですが、「あってはいけないバグを混入させたお前が悪い」という態度でバグレポートを書くのではなく、ともに解決しようとする姿勢を入れるだけで印象が大きくかわります。補足事項の欄等に代替手段として「この不具合は仕様として回避することもできるが、その場合には～との整合性を考える必要がある」等、解決を目指して検討した内容がわかる簡単な一言を入れられないか検討しましょう。

3. 日ごろから正確な文章作成に意識を向けよう

バグレポートの質は記述の正確さとわかりやすさに大きく依存します。正確な文章を書くためには、不正確になりがちな表現を意識することが重要です。「よくわからなかった」という指摘は素直に受け止めて次に活かしましょう。また、自分のメール、他人のバグレポートやメールからも学べることはたくさんあります。他人の文章を見て、自分ならこう書くという習慣をつけることもお勧めです。

文章書き一般のテクニックを紹介する書籍はたくさんあります。1回読むだけでなく、たまに読み直したり、仲間で議論したりすると新たな発見があります。開発プロジェクト終了後に、プログラマにとってわかりにくかったと考えられるバグレポートを2, 3取り出してプログラマ、テストエンジニアをまじえて話し合うこともお勧めです。お互いが何を知っていて、何を知らないのか、どういう場合に十分な説明が必要で、どういう場合にはあまり必要ないのかを明らかにできるからです。