『Looks Good To Me』を読んだ時に知った “Conventional Comments” というものがある。このフォーマットについて一度書いておきたい。
Conventional Commentsはコードレビューをするときに書くコメントのフォーマットについての提案である。
名前からわかるように、Gitのコミットメッセージのフォーマットとして有名な Conventional Commits にインスパイアされている。
Conventional Comments ではコードレビューコメントに次のような基本構文を与える。
<label> [decorations]: <subject>
[discussion]
Conventional Commitsと同様に、チームやプロジェクトの中で合意されたwell-knownなラベルのリストの中から選択することで、そのコメントの意図を明確にできる。Conventional Commentsは考え方としてはおもしろく、フォーマットは無駄がないものだと思いつつ、これがうまくいくかどうかはチームのラベル設計・定義のセンスに依存する度合いが強いように感じている。
nitpick についてはそもそもnitpickなコメント自体ノイズなのでやめておきたい。なのでラベルも不要だろう。そんなラベルをつけるくらいならコメントしなければいいのだ。
suggestion も意図が読みづらい。その提案の温度感というか、却下していいのかどうかがコンテキストフルになりがちだ。デコレーションのほうで blocking や non-blocking と補足しなければならないのでこれもいまいち。issueもそうだ。問題だと指摘するのはいいが、そのプルリクエスト中で直してほしいのかイシューチケット化しておけばいいのか、結局「どうしてほしいのか」がわかりにくい。
LGTM本の著者エイドリアン氏のチームでは needs change / needs rework / align / levelup / nitpick という5つのコメントシグナルを使っていたらしい。どれがblockingな指摘なのかは定義を覚える必要があるため、個人的には needs xxx のフォーマットで揃えたほうがいいのではと思う。いちばん重要なのはそのコメントがプルリクエストをブロックしているのかどうかの識別性だ。
たとえば、ラベルに!をつけることでblockingであることを示すとどうだろう。suggestion!やrefactor!のように使うことで、その指摘が解消されるまで承認できないことを示す。逆に!がついていないものは承認を止めないものとして扱うという合意があれば、コードレビューを受け取る側もコメント対応の優先順位がつけやすいのではなかろうか。nitpick!なんてありえないわけなので考えることは減る。
Conventional Commitsのほうでも!は破壊的変更を含むことを示すシグナルになっている。その対応からしても、PRに対して変更を要求することはイメージしやすいだろう。このような工夫ひとつで、コードレビューを受けたあとの「このコメントへの対応は必須だろうか？」と悩む時間がなくなると思えば安いものだ。
ところで、AIエージェントによるコードレビューをさせる際に、Conventional Commentsに準拠するよう指示してみたが、それなりによく機能した。出力を安定させるためのフレームワークとしては上々だ。しかし教育目的でもない限り、AIからpraiseをもらったところで何も嬉しくないし、nitpickはトークン消費のムダなので、そういうラベルは禁止してsuggestionやissueのような限られたラベルのみを出すように強く規定したほうがよさそうである。