はじめに
Supershipグループ Advent Calendar 2023、一発目の記事を担当する新卒2年目の永井雄也です。広告の配信サーバーを作っています。現在、私が所属しているチームには、コードレビューコメントのルールがありませんでした。ルールがない状況下で、私はレビューコメントの読み手、書き手、それぞれの視点で不満を持っていました。まず、読み手視点の不満は、コメントへの対応の有無や優先度を把握するために、一つ一つコメントを読んで、意図を汲み取らないといけないことでした。以前いたチームでは、ルールに基づいて、ヘッダーとしてラベルがコメントに付与されており、コメントから意図を汲み取らなくても、ヘッダーの情報で機械的に対応の有無や優先度を把握できてきたので、その差分で不満を感じていました。また、コメントを書き手視点の不満は、文章表現で対応の必要性や優先度を伝えなければならないため、言葉を慎重に選ぶ必要があり、ルールがあったチームでコメント書いていた頃より、コメントを書く時間が長くなってしまったことです。これらの不満を解消するために、以前いたチームと同じようにコードレビューコメントにルールを導入するという手段でレビューコメントの書き手、読み手視点の不満解消を試みました。
コードコメントレビュールールについて調べると、下記のようなフォーマットで must、 nits、 imo などのラベルをヘッダーとして利用するルールについて書かれた記事が複数出てきます。
[must]
コメント内容 ~
当初は同じようなルールを採用するつもりでいました。ただ、以前のチームで同じようなルールでレビューコメントを書いていた時、思い返すと下記のような不満を感じていました。
- レビュワーとして、imo や nits のどちらをラベルの付け方に悩みがち
- レビュワーとして、内容的には imo や nits だけど、必ず対応してもらいたいが表現しづらい
- レビューイとして、imo や nits など微妙ラインのラベルの対応優先度がわかりづらい
そのため、別の参考になりそうなルールを探すことにしました。
探していると、Conventional Commits のコメント版のような Conventional Comments というルールを見つけました。Conventional Comments を下地にすれば、 must, nits, imo などのラベルをヘッダーとして利用するルールの不満を解消したコードレビューコメントルールが作れそうだったため、Conventional Comments をベースにルールを作ることにしました。
本記事では、Conventional Comments のチームに合わせたカスタム内容と Conventional Comments のカスタムルールを反映して、実際に得られた効果を紹介します。これらの内容について、Conventional Comments の要素の内、カスタムしてメリットが得られる要素、私のチームに合わせたカスタマイズの内容、実際に得られた効果の順で説明していきます。
Conventional Comments の説明は、本家の説明にお任せして、割愛しています。本記事は Conventional Comments を理解している前提で書いているため、本記事を読み進める前に、本家の説明を読むことをお勧めします。
TL;DL
今回私の所属するチームでは、Conventional Comments を
- フォーマットに従う条件は、相手にアクションを求めたい時だけとする
- label は、
issue、suggetion、todo、questionの 4 つに絞り、優先度の意味合いは一切含めない - decorations は優先度の意味合いを表明する場として活用し、チームでは
non-blockingなコメントの方が多かったため、blockingが付与されていない場合、例外なくnon-blockingと看做す
のようにカスタマイズしました。１ヶ月程度運用していましたが、ルールが無い時と比べて、レビューコメントの読み書きの時間短縮は実感できています。また、ルール適用後に must、 nits、 imo などのラベルをヘッダーとして利用するルールで感じていた不満を今のところ感じていません。
もし、記事を読んで、Conventional Comments をベースにルールを作ろうと思った方は、チームのニーズに合わせて、以下の要素を羅列順にカスタマイズしていくと、いいと思います。
- フォーマットに従ってコメントを書くべき条件
- 扱う label の種類と定義
- 扱う decorations の種類と定義
カスタマイズしてメリットが得られる要素
Conventional Comments はいくつかの要素で構成されていますが、ルールをチームに合うように微調整する過程で、チーム毎にカスタマイズし、メリットが得られるなと思った要素は、
- フォーマットに従ってコメントを書くべき条件
- 扱う label の種類と定義
- 扱う decorations の種類と定義
です。
チームのニーズに合わせてフォーマットに従ってコメントを書いた方がいい条件を定義することで、全コメント適用と比べて、導入時のチームへの負荷を低減する効果を期待できます。本家の説明では、フォーマットに従う条件について提示されていません。全てのコメントにフォーマットを適用する前提のルールであると想像できますが、全コメント適用はチーム規模、ルールの導入目的次第では、明らかにオーバースペックで、レビューコメントを書く負荷を増やす恐れがあります。ルール適用後のチームへの負荷を減らすために、脳死で全てのコメント適用ではなく、チーム規模、ルールの導入目的に合わせて、フォーマットに従う条件を定めて、フォーマットに従う頻度を調整することをお勧めします。
label の種類や定義をチームのニーズに合わせて最低限にすることで、コメント時の脳のリソース消費を低減する効果を期待できます。本家の説明には強く推奨のラベルが ９ つ定義されていたと思います。ただ、フォーマットに従う条件同様、チーム規模、ルールの導入目的、上記のフォーマットに従う条件次第では、推奨の 9 つの label はオーバースペックで、全く使わない label が発生すると思います。例えば、相手にリアクションに求めないコメントはフォーマットに従わなくてもいいという条件をつけた場合、notelabel は使われず、コメントの書き手はフォーマットに従わないコメントで済ませると思います。いらない選択肢を排除しておいた方がコメント時に label を選ぶ脳の消費リソースが少なくなるはずなので、チームのニーズに合わせて、label の種類や定義をカスタマイズすることをお勧めします。
チームのニーズに合わせて decorations 種類や定義を最低限にすることで、decorations が １ つのコメントに大量付与される状況を未然に防ぐ効果を期待できます。本家のルールにおいて、decorations は複数付与可能で、label より表現力が高い要素です。decorations は複数付与可能というルールに不満はありませんが、 表現力が高いが故に、多くの decorations が 1 つのコメントに付与される可能性があります。本家の説明にもありますが、これは読み手に悪影響を与えかねないので、そもそもたくさん付与されるという事態が起きないように decorations の種類と定義をチームのニーズに合わせて最低限にすることをお勧めします。
チームに合わせたカスタマイズ内容
今回はチームのニーズに合わせて、フォーマットに従って書く条件、labelの種類と定義、decorationsの種類と定義を以下のようにカスタマイズしました。
- フォーマットに従ってコメントを書くべき条件は、相手に何かしらのアクションを求めたい時としました。
- label は必要になったら足すスタイルで、優先度の意味を取り払った
issue,suggetion,todo,questionの4つに絞りました。 - decorations は
blockingとnon-blockingを使用し、blocking付与されていないコメントは全てnon-blockingとしました。
フォーマットに従ってコメントを書く条件は、相手に何かしらのアクションを求めたい時、具体的なケースは、レビューコメントのスレッドの先頭です。ルールが無い状況下の不満として、「対応する必要があるコメントなのかの判断をコメントの中身を見なきゃわからない」がありました。コメントを見た瞬間、フォーマットに従っているかどうかで判断できるようにするため、 相手に何かしらのアクションを求めたい時だけフォーマットに従ってコメントを書くことにしました。具体的には、レビューコメントのスレッドの先頭で使うことを想定しています。適用しないケースの具体例を挙げると、コードを補足するだけのコメントやスレッド内のコメントです。スレッド内のコメントのほとんどは相手にアクションを何らかのアクションを求めるコメントで、適用すべきか悩みました。しかし、スレッドでやり取りが始まれば、お互いにアクションが必要な事を暗黙で把握しているはず、また、脳死で全部のコメントに適用より空気読みやコンテキストの把握に脳のリソースを使うが、スレッド内コメント全適用の手間の方が大きいと判断し、スレッド内コメントは適用なしとしました。
必要になったら足すスタイルで、labelは下記に示す対応度合いの意味を取り払った4つのラベルに絞りました。今回の label のカスタマイズ内容を下記の表に示します。相手に何かしらのアクションを求めたい時だけフォーマットに従うとしたので、アクションを求めないコメントに付けられそうな note:、praise:、thought:、chore:、note: を削除しました。また、todo:で代替できそう、かつ、must, nits, imo などのラベルをヘッダーとして利用するルールの不満で挙げた通り、似たようなラベルはラベルをつけるときの悩みの種になり得るので、nitpicks:`も削除しました。label を計4つに絞り、必要になったら追加するスタイルにしました。それぞれのラベルの意図も本家と変えていますが、特に大きく変えた部分はラベルに優先度の意味合いを一切含まず、対応必須かどうかは decorations に従うとした点です。must, nits, imo などのラベルをヘッダーとして利用するルールの不満であるラベルに優先度の意味合いが含有されてしまっているが故に、やりづらくなっている部分を解消するために、ラベルには優先度の意味合いを一切含めていません。
| ラベル | 意図 |
|---|---|
| issue | 問題は理解、把握しているけど、その解決策は思いついておらず、問題提起だけ行なっていることを読み手に伝えたい時に付与する。優先度の意味合いは含まない。 |
| suggetion | 改善案はあるけど、読み手と改善案について話し合いたいことを読み手に伝える時に付与する。 優先度の意味合いは含まない。 |
| todo | 相談せずとも直した方がいい箇所を読み手に伝えたい時に付与する。 優先度の意味合いは含まない。 |
| question | 質問していることを読み手に伝えたい時に付与する。 優先度の意味合いは含まない。 |
decorations は優先度の度合いを表明する場として、non-blockingとblockingを採用し、使用頻度が高いnon-blockingをデフォルトとしました。decorations のカスタマイズ内容を下記の表に示します。label に優先度の意味合いを含めない代わりに、優先度の表明を decorations に委ねることにし、non-blockingとblockingを採用しました。non-blocking と blocking、どちらを default にするか、現状のコメントにおける non-blocking と blocking に頻度に従うことにしました。頻度の多い方を選べば、単純にタイピング数が減るので、我々のチームでは non-blocking を default にしました。
| ラベル | 意図 |
|---|---|
| non-blocking | できればアクションが欲しいけど、 アクションがなくても approve を妨げないことを表明するために付与する。blocking がない場合、全て non-blocking と看做す。基本、付与しない。 |
| blocking | 何らかの結論に至らないと approve しないよを表明するために付与する。 |
得られた効果
１ヶ月程度、カスタマイズ後のルールを運用しましたが、ルールの適用前に比べて、レビューコメントの読み書きの時短を、must、 nits、 imo などのラベルをヘッダーとして利用するルールで感じていた不満なく、実感できています。
- 期待した通り、フォーマットに従っているかどうかでアクションが必要なコメントか否かを判断できるようになったので、その判断に使う脳のリソースや時間が減りました。
- approve を妨げているコメントかどうかも blocking decoration がついているか否かで判断できるようになったので、こちらも期待通りの効果が得られています。
- blocking decoration をつけるだけで、機械的に対応必須を伝えられるので、言葉選びに使う時間が少なくなり、レビューコメントを書く時間の短縮につながっています。
- label に関わらず、default は non-blocking にした事で、ラベル毎に、non-blocking, blocking どちらがデフォルトだっけと悩む時間を消費せずに済んでいます。
- デメリットも挙げられると良かったのですが、まだ運用して１ヶ月程度なので、デメリットは見つかっていません。
おわりに
まだ導入して１ヶ月程度ですが、得られた効果で示した通り、期待していた効果は得られています。このまま使い続けて、メリットやデメリット、いいカスタマイズを探していければいいなと思っています。また、Conventional Comments のフォーマットはプログラムでパースしやすい形式になっているので、この特性をうまく活用する方法も模索したいですね。以上、Conventional Comments をベースにコードレビューコメントルールを作った話でした。我々のチームと同じ悩みを抱えているチームは Conventional Comments をベースにコードレビューコメントルールを作ってみてはいかがでしょうか？
最後に宣伝です。
Supership ではプロダクト開発やサービス開発に関わる人を絶賛募集しております。
ご興味がある方は以下リンクよりご確認ください。
Supership 採用サイト
是非ともよろしくお願いします。