Issueを書く際の心構え

弊社ではIssue管理ツールとしてGitHubのIssueを利用しています。Issueは以下のようなフォーマットをプロジェクトの.github/ISSUE_TEMPLATE.mdに登録しておくことで、GitHubでIssueを立てたときに自動的にひな形が補完されるようにしています。

## なぜこの対応が必要か？

## この対応により提供される価値

## その他・備考

ただ、最近佳境にあるプロジェクトもあるせいか？、曖昧(適当？)に書かれているIssueがたまにあり、私自身も、時間がないときにとりあえず急いでIssueを立てておこうとして、分かりづらいIssueになってしまっていることがあります。

分かりづらいIssueは以下の様な弊害をもたらします。

• 実装者がIssueを立てた人に意味を再確認しないといけない。
• 実装者がIssueの内容を捉え誤って、間違った実装をしてしまう。
• レビューする人がIssueを参照しても、何を実装したかったのか分からない。

Issueをきちんと書くにはそれなりの時間がかかることもありますが、上記デメリットを解消できることを考えると、そこに多少の時間をかける価値がある場合も多いです。

今回は自戒の念も込め、実際にあったイマイチなIssueをデフォルメした上で、Issueを書く際の心構えについて書きたいと思います。これはもちろんGitHubに限らず一般的なチケット全般に言える話でもあります。

タイトル

Issueの一覧を見るときにはタイトルを見ることになるので、タイトルを見てどういう内容かを把握できるように簡潔に書くことが大切です。

良くない例:

ELBはAWSのElastic Load Balancerのことを言っていますが、これはお互いに共有している前提でお話しします。

上記タイトルはコンテキストを共有している人だったら分かるかもしれませんが、共有していない人には誤解を与えてしまうかもしれません。

分かりにくくなっている一番の要因は、「無視する」という言葉でしょうか。「無視する」という言葉は主語と目的語を要求しますが、主語が書かれていません。タイトルでは主語は省略されることは一般的ですのでそれ自体はいいのですが、一般的に「無視する」というのは「人が無視する」という場合に使われることが多いのではないかと思います。ですので、人が目視か何かでログを無視するのか、それとも何らかのプログラム的に無視するのか、もしくは他の何かが無視するのかが分からず混乱してしまいます。
また、ちょっと細かい話ですが、「health_check」というのはおそらくELBからのヘルスチェックのことを言っているのだろうなとは想像できますが、「health_check」という一般的な単語はありません。

実際にはこのIssueで対応したいことは、

「Railsのアプリケーションログに、ELBからのヘルスチェックのアクセスが記録されていることがイヤなので、ヘルスチェックのアクセスをロギングしない対応をする。」

というところでした。
それを踏まえてタイトルを修正してみると、

「RailsアプリケーションログにELBからのヘルスチェックアクセスをロギングしない対応」

などといった改善案が考えられます。
タイトルは簡潔にかつ的確に書く必要があり、言葉をうまく選ぶことが大切だと思います。

コメント

機能エンハンスの場合を取り上げます。

良くない例:

情報が少なく、これだけ見るといろんな疑問が浮かんでくると思います。

• 商品画像登録・更新APIは誰が使うAPIなんだろう？
• API仕様から決めるのか、API仕様は決まっていて実装するだけなのかどっちだろう？
• API仕様から決めるんだったら、何を参考にして決めればよいんだろう？
• API仕様があるんだったらどこにあるんだろう？

上記のような情報は追加する必要があるでしょう。
また、最後の「提供される価値」が「商品画像登録・更新API」というのは若干苦し紛れに書いた(埋めた)と思われますが、意味のない情報ですのでそれだったら書かないほうがいいかと思います。

それを踏まえてちょっとだけ修正するとこんな感じでしょうか。(実プロジェクトと関係ない架空のストーリーなのでなかなか書くのが難しいですが、実プロジェクトだともっと情報が必要になってくる場合も多いと思います。)

また、Issueがバグレポートの場合は違った内容が必要になりますが、また別の機会に。。。

まとめ

分かりやすいIssueを書くのは奥深いものです。結局、一番大事なことは読む人の立場になって文章を書くというところだと思います。書いた後にさっと読みなおして、他の人に分かるかなと考えるところから始めるところから始めるのもいいのではないでしょうか。

shimo