コミュニケーションアドベントカレンダー9日目の記事です。
課題管理ツールのコメントについて自分の中で守っているルールがあるのでそれを共有したいと思います。
自分ではない誰かが、いつか見る事を想定する
mironalさんの投稿、『issue を雑に作らないために』の
どの画面での遷移アニメーションだよ！
そもそも遷移アニメーションってなんだよ！
再現手順は？
どのバージョンで発生するの？
バグならバグってラベル付けて！
誰かにアサインしようよ！
誰もこれ見て状況を把握できねぇよ！！！
にあるように課題管理ツールのコメントは 自分ではない誰かが、いつか見る事 を想定して書くべきです。
よく見る悪い例
チケットのステータスだけが変わりクローズされたチケット(かなり極端に悪い例ですが)
おそらく実際に開発していた担当者は何かの方針のもとに進めていると思われるが、あとから第三者がみた時には何があったかはわからない状態。
コメントには想いを残す
自分ではない誰かが、いつか見る事 を想定して私はコメントに 想い を書くようにしています。
ここで言う 想い とは どうしてそのように結論づけたのか ということを言葉にしたものになります。
例えば
- モジュール間を疎結合にするためにwrapperを作るべきだが納期的に厳しいので直接呼び出す実装にした
- APIのパラメータの必須/任意が不明だったのでお客様に確認したところ任意だったことがわかった
- このチケットではひとまず動くための実装しかしていない
などです。
想い が書いてあることで、その時にその人がどう考えて進めたかをコメントから知ることができます。
何故みんな書かないのか？
A. 面倒くさいから
おそらく書かない人のほとんどが面倒くさいからと感じているのではないでしょうか。
つまり 面倒くささ > メリット となっているのです。
想いが役に立つ時(メリット)
チケットを後から見るタイミング = 不具合発生時
チケットを後から見るタイミングは往々にして不具合が起きた時が多いと思います。
その際に『よく見る悪い例』のようなコメントが空っぽのチケットだと情報が何も得られず一から調査しなければなりません。
例えばこのチケットに
loginのAPIはサーバの仕様がまだ未確定な部分があるため変わる可能性があるが進捗を進めるために2015/XX/XX現在の仕様で実装している
のようなコメントが書かれていれば、APIの仕様が変わったのかもしれないというあたりをつけることができます。
まとめ
- 課題管理のコメントは 自分ではない誰かが、いつか見る事 を想定しよう
- コメントには 想い を残してあげよう
- 面倒と思わずに長い目で開発していこう
開発は一人で進める事の方が少ないと思います。
なので常に自分以外の人のことを意識してあげると開発がスムーズになると思います。
ただあくまで 想い は課題管理ツールのコメントに必要な一要素であり、それだけではまだ不足かと思います。
先ほど引用させて頂いたmironalさんの投稿、『issue を雑に作らないために』のこの辺りのツッコミでもあるように、チケットに書かなければいけないことはたくさんあります。
どの画面での遷移アニメーションだよ！
そもそも遷移アニメーションってなんだよ！
再現手順は？
どのバージョンで発生するの？
バグならバグってラベル付けて！
誰かにアサインしようよ！
誰もこれ見て状況を把握できねぇよ！！！
その辺はまた記事にしたいと思います。