
エンジニアに分かりやすくバグを報告するバグレポートの書き方
こんにちは、フロントエンドエンジニアのいなばです。
案件の開発終盤、こんなことが起きていませんか?
しかし、蓋を空けてみると……書き方の悪いissueが乱立!
バグの内容を把握するのに時間がかかる!
結局わからないのでissueを立てた本人に聞く→結果的にコミュニケーションコストが増える……。コミュニケーションコストを減らすためのツールなのに、やりとりが何往復もしていたら本末転倒ですよね。
そこで、今回はGithubやbitbucketのissue機能を活用したデバッグフェーズでのタスク管理のコツをご紹介します。
そもそも、どんなissueが“悪いissue”なのでしょうか?
例を見てみましょう。(極端な例ですが)
ドキュメントを開こうとしたとき、表計算がクラッシュしてました。確か、表計算は図表を含んでいたような気がしないでもないような。Windowsを使用しています。これは本当によくない問題だし、これは今にでも直すべき問題だよ。ところで、このアイコンは実にむかつくね。こんな醜いアイコンを使い続けるなら、誰もこんなソフト使わないよ。あ、それとオバあちゃんがワープロについて問題があるって。ちゃんと動作しないしないらしい。では。
引用元:Open Office Issue報告ガイドライン
http://openoffice-docj.osdn.jp/tr/translated/bug_writing_guidelines.html
ひとまず分解してみましょう。
なんだかふわっとしていますね。
アイコンは別の問題ですし、ワープロの問題はそもそも関係がなさそうです。
また、クラッシュすることの原因に図表を含んでいることが関係しているのかハッキリしませんし、WindowsのOSとアプリのバージョンもわからないので、まずは再現できる環境と手順を調べなくてはなりません。
そして再現できない場合には、issueを立てた人に詳しく聞くことになるでしょう。
Win NT4.0(Service Pack5)上で10.13.00ビルドを使用すると、添付した表計算ドキュメントを開くたびにクラッシュします。またLinux(RedHat 6.2)上で同じことをしたら、10.13.00のLinuxビルドを使っても同じことが再現できます。
そのドキュメントから図表を取り除いたら、問題なく開くことができました。引用元:Open Office Issue報告ガイドライン
http://openoffice-docj.osdn.jp/tr/translated/bug_writing_guidelines.html
こちらも分解してみましょう。
すっきりとしましたね。
問題点 | 添付した表計算ドキュメントを開くたびにクラッシュする。 |
---|---|
再現手順 |
|
ゴール | Win NT4.0(Service Pack5)、またはLinux(RedHat 6.2)上の10.13.00ビルドで添付した表計算ドキュメントを開いても、クラッシュしないようにする。 |
これならすぐ修正作業に取りかかることができそうです。
悪いissueを乱立させないためには、
をプロジェクトメンバー全員に明記してもらえるように、issueの書き方(フォーマット)を決めてしまうのが良いでしょう。
バグレポートフォーマットは、当社のディレクターJackが書いている記事も参考になるかと思います。
エンジニアに分かりやすくバグを報告するバグレポートの書き方
定着するまでに時間がかかるかもしれませんが、コミュニケーションコストを減らすために地道に布教していきましょう。
問題点を伝える際は、以下のことに意識しましょう。
問題は細かくした方が解決が早いです。
問題点が明確に書けないときは、下記2点に気をつけてみましょう。
問題が大きすぎたり複数の問題を扱ったりすると、issueの重複も生まれやすくなりごちゃごちゃします。またcloseもしづらくなり、いつまでも残ってしまうことになりがちです。
つづいて、他の人も再現できるように再現環境と手順を明確にしましょう。
非エンジニアは技術的な難しいことを頑張って書かなくてOKです。
頑張って書いたのにかえってわかりづらくなるのは悲しいですし、箇条書きでも十分伝わるので。
ただし、
この2点はとても大事なので気をつけましょう。
解決方法を明記してあげたほうがより親切ですが、問題点と再現手順が明確であれば解決法も明確になっているはずです。