開発の現場では不具合修正の案件は、チケット、プロダクトバックログアイテム(PBI)、github issuesなどで管理していると思います。
私の持論ですが、バグは見つけたらすぐ直すべき派なのですが、必ずしもすぐに対応できない場合もあると思います。(優先順位、工数、難易度、必要な意思決定のサイズ等に起因して)
すぐにやれない場合は、ちゃんと情報を整理しておくべきです。
着手できるようになった際に、0ベースで調べ直すことなく、低コストで着手できるレベルまで情報を揃えておく必要があります。
その時間すら惜しい場合もありますが、不具合を直すよりは短時間でやれるはずですし、直したほうが早いなら、わざわざ整理して置く必要もなく、さっさとその場で直せばいいので、うだうだ言わずにすぐ直せないならちゃんとやりましょう。
それが対応する人への思いやりだし、開発チームとしてやるべき仕事です。
不具合チケットに書くべき内容
個人的にやっている内容と、やれているか怪しい内容がありますが、ひとまずこれだけ揃えていれば、十分だろうと考えているものを列挙していきます。
裏を返せば、私がこれだけ整っているバグチケットを見たらうれしいレベルの内容でもあります。
【MUST】バグレポートに相当する内容
不具合修正のときは、事象を再現させて、その事象が直るようにコードを修正するという手順を踏みます。
そのため、バグレポートに書かれているべき以下の情報
- バグの再現方法(できるだけ詐しく)と発生頻度
- 再現方法 = 発生条件(設定、環境、アカウントなどの情報)、再現手順(どういう操作か)、起動経路など
- 本来の仕様(バグがない場合の望ましい動作。こうあるべき、という自分の意見でかまわない)
- 期待結果と呼ぶ場合もある
- 実際の動作(完全でなくても、自分の記録した範囲で詳しく書く)
- バグの事象です。再現方法を実施したときにどう言う結果が不具合として起こるのか
【視覚的に分かる場合はMUST】画面キャプチャ等の視覚的に不具合が分かる情報
Webサービス系の不具合であれば、画面に不具合の事象が顕在化する事が多いと思います。
画面を見れば不具合とわかるものは、画面キャプチャを添付すべきです。
※gifなど、動作がわかるものだとより良いでしょう。
その不具合修正をする人が必ずしもその画面の有識者とは限らないからです(弊社では1年目のメンバーのオンボーディングの一環で軽微な画面の不具合修正を担当することも多い)。
視覚的な情報を提供することで、その不具合に対する解像度が高まります。
【SHOULD】不具合の原因箇所
ソースコードの場所が特定できている場合は必ず記載すべきです。
実際に対応する人に対して、(実は他の部分で修正するのがベストなのに別の所を指示してしまうことで)バイアスをかける可能性もありえますが、少なくとも0ベースでコードを探す事による工数の浪費は削減できます。
調べきれていない場合は「ちゃんと調べられてないけど、このパッケージらへん」「こういう名前のクラスのこういう処理でこういう状態になっているはず」のように、仮説ベースであっても良いので書かれているだけで、大量のソースコードがら探し当てる作業は減らせますし、いきなり仮説の検証から入れます。(仮説構築は経験が浅いほどコスト高い)
【COULD】修正方針
直す工数が取れなくても、「私だったらこんな感じで直す」を書いておくことで、ここでも修正方針を考える部分を削減できます。
不具合は一刻も早く潰す方が良いので、(「おそらくこんな感じだろう」が)わかっているなら書いておいた方が良い。
【COULD】修正による影響範囲(とその仮説)
修正方針を記載するのであれば、合わせて記載しておいたほうがよいのが、修正による影響範囲です。
疎結合高凝集なコードの場合、影響範囲の推定、調査はそれほど大変ではない場合もありますが、それ故に様々なところで使われている場合もあります。
レガシーコードやスパゲッティコードの場合は、影響範囲を読みきれない場合もあります。
推測レベルでも、無いよりはあったほうが良いです。
自分の持っている情報や自分の考える観点を他者がもっているとは限らないためです。
例えば、
- その修正方針によって(良くも悪くも)動作が変わる可能性がある機能や画面は何なのか
- どの程度の範囲に影響がありそうなのか
- etc
最後に
文字でダラダラ書いてきましたが、
自動テストが整備されていて、6~70%以上のカバレッジが担保されている恵まれた開発環境下では、Shouldくらいまであれば十分な気もします。
影響範囲を調べずとも、動作が変わるなら自動テストが失敗するはずだからです。
一方でそのような恵まれた環境ではないプロダクトの場合は、不具合修正の過程で自動テストの拡充とともに影響範囲調査を丁寧にやることで、機能への理解が深まるとともに、トラブルシューティングへの耐性・スキルも上がるので、特に若手の皆様においては、手を抜かずしっかり向き合ってほしいと思います。