はじめに
レビューコメントにメタ情報を持たせるためにラベルバッジをつけるということをやっています。
2021年くらいから以下の記事を影響を受けて真似し始めました。
Draft から1年以上
この記事を公開しようと思って1年以上寝かせてしまいました
やってみて、自分にあった表現に見直したのでその紹介です。（カラーコードも見直しています）
Text Blaze の利用手順は上の記事で詳しく紹介されているのでここではしません。
レビューコメントにメタ情報を含めるのは、コメントを読む側はもちろん、コメントをする時点で、どういったリアクションを期待するのか、これは修正必須なのか、それともそうではないのか、期待する内容が曖昧なコメントを防ぐことができるので、レビューのやり取りがやりやすくなる効果があると思って取り込んでいます。
自分の設定内容
GitHub
| badge | 期待するリアクション | 意味 | Text Blaze - shortcut | Text Blaze - content |
|---|---|---|---|---|
 |
回答必須 | 確認 | /ask |
 |
 |
修正必須 | この対応がされていないと Approve できない | /must |
 |
 |
修正任意 | こういう表現もあります | /imo |
 |
 |
修正任意 | 細かい指摘 | /nits |
 |
 |
修正不要 | 今後の改善点 | /next |
 |
 |
- | コード理解・解説のためのメモ書き | /memo |
 |
 |
- | 良い点 | /good |
 |
BitBucket
BitBucket のレビューコメントでは GitHub とは異なるレンダリングを採用していて、 height を指定する必要があります。
| badge | Text Blaze - shortcut | Text Blaze - content |
|---|---|---|
|
/b/ask |
{height=20} |
|
/b/must |
{height=20} |
|
/b/imo |
{height=20} |
|
/b/nits |
{height=20} |
|
/b/next |
{height=20} |
|
/b/memo |
{height=20} |
|
/b/good |
{height=20} |
解説
suggestion を除外
冒頭の記事に含まれていた suggestion はあまり使わなかったので、除外しました。
Code Suggestion を利用する時、レビューコメントの段階として、以下があり、どのケースにおいても提案（＝suggestion）なので、 suggestion 単独で利用するのは相応しくないと感じました。
- must: 推奨されているので必ず修正して欲しい場合
- imo: 推奨されているので自分ならこちらで書く場合
- nits: 細かいけど、単に推奨されている書き方を紹介する場合
ask のカラー変更
blue だと suggestion の色と被っていて避けることにしました。（除外したので色の重複は気にしなくても良くなりましたが）
回答が得られないと判断が難しく、コードレビューにおける意味の理解と把握において重要であることから、カラーコードは黄金の yellowgreen を選択しました。 Googleのソフトウェアエンジニアリングから学ぶコードレビューの記事でコードレビューそのものについて詳しく書いています。
コードレビューは、ある変更がより広い対象にとって理解可能かどうか試す最初の試練である
next を追加
レビューをしていて、この Pull Request のスコープ外だけど、改善点として気づいたことをコメントとして残します。
今回修正不要だけど、改善点であることを明確にし、このラベルバッジのコメントを Issue として作成すると対応漏れの防止にもつながります。
memo を追加
コード理解や解説のためにレビューコメントを残すのが効果的なケースがあります。
セルフレビューだったり、他のレビュワーや、後で自分でレビューを見返すシーンだったりで相互理解の助けになります。そのような意味合いを他のレビューコメントと区別するために利用します。ただ、 memo に関しては、絵文字の 📝 がわかりやすいので、バッジラベルより絵文字で代替することが多いです。
good を追加
レビューをしていて、ここは特に良いと思った点をコメントするようにしています。
単に褒めているだけという意図を明確にするためにこのバッジが目印になります。
おわりに
ここまで Chrome Extension を前提に書いてきましたが、 GitHub に限定するなら、 Saved replies も活用でき、以下の記事で紹介されています。ここで紹介したラベル付けとも異なり、考え方の参考になるので、合わせて読んでもらえたらと思います。
Discussion
記事のご紹介ありがとうございます！
ラベルバッジで行うとコメントの一覧性が高くなり、優先順位がより明確になりますね 👍🏻
また、
goodラベルはお互いのモチベーションを高める良い方法ですね！私たちのチームでも
goodを追加してみようと思います。以下の定義だと TextBlaze で
{height=20}の部分が Formula と認識されてしまって、出力されずうまく機能していなかったです。後ほど、 BitBucket の記述を訂正します。
以下のように
{=}コマンドを利用して Formula に指定テキストを出力する方法でうまくできました。以下のレファレンスでも
{=}コマンドについて触れられていそうですが、ここから読み解くのは難しかったです。