すべてのコメントは読まれるために書かれる
1日の内でどのくらいの時間をチケットを探し・読むことに使っていますか？
4スクロール分のコメント列を全て読んでも要領が得られず、結局担当者に聞きに行ったり（そして覚えていないと言われたり）、自分で調べたりすることはないですか？
コメントを書くときに注意する4つのポイント
- 誰に向けて書いているのか？（対象）
- 何のために書いているのか？（目的）
- 記載する情報の中で最も重要なものは何か？（要点）
- 要点が最短の時間で伝わるようになっているか？（構成）
「なぜそれをコメントに残すのか？」という意図（目的）が明らかになれば、どう書けば目的を達成できるかの判断が楽になります。
情報が増えるほど記載順序や構成に注意が必要になるでしょう。
もちろん最重要なのは記載される「情報そのもの」であって「どう書かれたか」ではありませんが、以下のようなUXデザインに関する知識も情報伝達の助けになると思います。
Webコンテンツを読む視線の軌跡は“F”を描く
視野狭窄と選択的注意
よくない構成の例
- 対象…開発者
- 目的…試験結果報告
- 要点
- NGの情報（NGがあった場合）
- 試験内容
試験環境： 環境1, 環境2, 環境3
確認内容：
* 条件aで期待動作Aになること
* 条件bで期待動作Bになること
* 条件cで期待動作Cになること
* 条件dで期待動作Dになること
試験結果：
| 環境1 | 環境2 | 環境3 | |
|---|---|---|---|
| 条件aで期待動作Aになること | OK※2※3 | /※1 | OK※2 |
| 条件bで期待動作Bになること | ※4 | ※4 | OK |
| 条件cで期待動作Cになること | OK | ※5 | ※6 |
| 条件dで期待動作Dになること | OK | ※5※7 | ※6※7 |
※1: 試験対象外
※2: XXの条件で試験すること
※3: OOになることを確認
※4: クラッシュしたので別途記載
※5: 期待動作にならずにYYになる（修正前/後両方で同じ動作）
※6: 期待動作にならずにZZになる
※7: ※5,※6の状態になるが期待動作Dは満たす
問題点
試験結果が把握しづらい
※印しかない欄は未試験なのかOKなのかNGなのかぱっと見でわからず、表で書いている意味がない
NG・不明点が注釈に紛れている
※1以外は注釈とするのは不適切
（※1を確認内容に含めてもよいが、1件しかないので注釈でもよいかと…）
試験の条件・期待結果が分散して書かれている
※2: XXの条件で試験すること => 条件aに含めるべき
※3: OOになることを確認 => 期待動作Aに含めるべき
NGについての情報が不足している
※6: 期待動作にならずにZZになる => 修正前の挙動を調べて記載する
修正例
to: Aさん
試験を行いましたが、下記のような挙動になりました。
確認をお願いします。
- 環境1,環境2で条件bのときクラッシュする（環境3ではOK）
- 環境2,環境3で条件c,条件dのとき、期待動作にならない（NGか、期待動作の誤り？）
- 環境2の現状動作： YY (修正前/後で同じ挙動)
- 環境3の現状動作： ZZ (修正前は不再現)
- YY, ZZ の状態でも期待動作Dは満たす
--
試験環境： 環境1, 環境2, 環境3
確認内容：
- 条件aで期待動作Aになること
- 条件aにはXXも含める
- 期待動作AにはOOも含める
- 条件bで期待動作Bになること
- ...(略)...
試験結果： NG
| 環境1 | 環境2 | 環境3 | |
|---|---|---|---|
| 条件aで期待動作Aになること | OK | /※1 | OK |
| 条件bで期待動作Bになること | NG | NG | OK |
| 条件cで期待動作Cになること | OK | 要確認 | 要確認 |
| 条件dで期待動作Dになること | OK | 要確認 | 要確認 |
※1: 試験対象外
まとめ
- 目的を持ってコメントを書く
- 長文は読まれにくいので工夫が必要
コメントは情報を必要とする誰かにそれを提供する、秘書のような存在です。
クールで有能な秘書官を育成して、快適なチケット駆動開発ライフを送りましょう。