Conventional Comments それは コードレビューがみた光

おはようございます、こんにちは、こんばんは。
スペースマーケットでWebエンジニアをしているs0arです。

Switch2抽選落ちました。
意外と周りに当たってる人がいてびっくりしてます。
あんなもん普通の人間に当たるわけがないんだよなあ？
当たった人は任天堂に何を差し出したんですか？

あなたはコードレビューが好きですか？

あーしはけっこうすきかも〜（ギャル真似クソジジイ）

他の人が書いたコードから「こういうのもあるのか」っていう勉強になったりするし
読めば読むほどどんどん知識と経験値が蓄積されていくので大チャンスだと思っています。

だからどんどんやっていきたいしみんなもやろうぜ！コードレビュー最高！
ってさ…手放しで言いたいけどもやね？

コードレビューに対して感じる課題

ってのは少なからずあるわけっすよ。

オレオレラベル問題

現状、弊社ではレビューコメントに以下のようなラベルを付けていることが多そうです。

ラベル	説明
must	必ず対応してほしい
should	mustよりは重要度は高くないが対応すべき
imo	ワイトはそう思います
nits	些細な好みレベルの指摘
fyi	参考までに
ask, q	質問

…はい、わかりますか？

「多そう」です。
人によってつけてるラベルが違ったりそもそもつけなかったりです。

自分はレビューするときいつも思ってました。
「これはimo…nitsか…？ええいどっちもつけちゃえ〜」
「fyi…といいつつ好みな気もするんだよなあ…」
っていうね。
つけるラベルに迷っちゃう。
いや、そんなことに迷ってんなよって。

ひいては、温度感伝わりづらい問題

レビュー受ける方もなんか対応したほうが良さそうだから結局大体のコメントに対応しちゃう。
本当にそれで良いのか…？実はそれよりもっと別の大事なことに時間を使えるんじゃないか…？

指摘に終始しちゃう問題

「こうした方が良い」「こうすべき」が多くてさ…。
「このコード良いね！」とか、そういうの、少ない気がするな…。
もっと肯定感高めていきたいな…おじさん褒められたいな…（願望）

Conventional Commentsそれはコードレビューがみた光

ぼくがみた希望
Conventional Commentsそれはふれあいの心

https://conventionalcomments.org/

颯爽登場！銀河美少年（？）、Conventional Comments！！
（なんの脈絡もなく変なネタ放り込むのマジでどうかと思う）

ちなみに、字面のよく似たConventional Commitsっていう方もいらっしゃるんですが、
今回はあんたの話じゃないので大人しく引っ込んでてほしい。

Conventional Commentsのメリット

1. コメントの意図が明確になる

• 「これは直してほしい？それとも提案？」という迷いがなくなる
• 「言いたかったこと」がぶれない
• 緊急性が明確に区別される
• テキストベースのやりとりが効率化される

2. 心理的安全性が高まる

• 批判ではなく「提案」や「確認」として受け取れる
• praiseの導入で、レビューにポジティブな空気が生まれる（後述）

3. レビュー文化が統一される

• 「must//imo/nits」のようなオレオレラベルの解釈ブレが減る
• メンバー交代時のオンボーディングがスムーズになる

じゃあ具体的にどうなんの？

以降、自分がもし導入するとしたらの話をしますよ。
推奨されているラベルの運用よりは多少軽くします。

コメントの基本構文

<label> [decorations]: <subject>

[discussion]

• label：コメントの種類を示すラベル（例：issue, suggestionなど）
• decorations（任意）：コメントの性質を補足する装飾（例：blocking, non-blockingなど）
  • カッコで囲み、カンマ区切り
• subject：コメントの主旨を簡潔に表現した要約
• discussion（任意）：詳細な説明や背景情報、提案など

導入候補ラベル

ラベル	用途
issue	明確な問題の指摘
suggestion	明らかな改善提案（チーム方針や可読性など）
nitpick	好みによる些細な指摘
question	疑問点や意図の確認
note	共有したい補足情報
praise	良い点へのフィードバック

基本的には現状使っているラベルに準拠していますが、唯一同等のものがないのがpraiseです。
指摘に終始しがち、ともすればネガティブになりがちなコードレビューにおける清涼剤です。
ポジティブなフィードバックは非常に大事。
もらった側はシンプルに嬉しいし自信がつくし。
レビュアー的にもポジティブなフィードバックはしたいよね。
あ、でもむやみやたらとpraiseするのはやめようねと公式さんも言っています。

Do not leave false praise (which can actually be damaging).

おべっか使うなよってな。心からの賞賛を。

decorationsとしての blocking のみ導入（non-blocking は省略）

• blocking を必要な箇所に明示し、それ以外は原則非ブロッキングとみなす運用とし、コメントの負担を最小限にしながら緊急性は伝えられるようにします。

対立意見とか検討事項とか

と、ここまで書いてきたわけなんですけども。
そらたぶん色々言われたりすると思うんですわ。

現状のプレフィックスからの移行ハードルどうすんの？

以下のような点に配慮すれば良さそうと考えていますよ。

観点	配慮する点
現状維持派への配慮	無理に全員へ強制せず、まずは「使ってみたらどう？」のスタンスを取る
効果検証	実際に使った人の声を反映し、主観だけでなく客観的に広く良いものであると思われるように
スムーズな定着	小さく始めて成功体験を積み、無理なく受け入れられるように
説得力	全体提案の際に「試して、実際によかった」という裏付けを取る

てなわけで、こんな感じのステップを踏んだらどやろか？

1. Conventional Commentsの紹介

このブログなんだな。

2. 個人で試す（チームメンバーへのレビューで）

いったん従来のラベルを併記する形で運用。
慣れたら併記をやめます。

3. レビューを受けたメンバーにアンケート

実際レビュー受けてどうでした？をGoogleフォームで収集。
（レトロスペクティブで聞くとかでも良いかも）

4. チームメンバーの感触が良かったらチームで導入

しばらく試してまたアンケよ。
ソシャゲみたいだね（？）

5. それも良さそうだったらエンジニア組織全体に提案する

みんなでやろう、Conventional Comments。

現状言うほど困ってへんやん？

ぐぅ…そらそうかも…。
ただ、レビューでの指摘に対する温度差や、修正の必要性が伝わりにくいケースは意外とありますよね？あるんです。
Conventional Commentsは、 その差を埋めるための「共通言語」 として、レビューの透明性と安心感を高めてくれる仕組みなんですよ。

想定Q&A

敵（冗談）	ワイ
「今のやり方でとくに困ってないよ」	「大きな不満がなくても、伝え方を明確にすることでレビュー時間が短くなったり、受け取り手の心理的負荷が減るんだZE☆」
「ラベル多いと逆に面倒じゃね？」	「最小限のラベルで始めるからmustとかimoみたいな現状の運用と大きく変わらないんすよねHAHA」
「今さらルールを変えるの？」	「今までの良い文化は活かしつつ、より意図が伝わる共通言語として補強するからもっと良い文明になります」

Conventional Comments 始めます（超個人的に）

とりあえず個人的に（といいつつ若干チームは巻き込むんだけど）やってみようかなと。
やってみて「やっぱしっくりこない」ってなるかもなんですが、見た感じは結構良さそうと感じています。
もし気に入ったら前述の流れで浸透させていきたいなあ〜と目論んでいたりしますよ、ふふん。

蛇足

この記事を書こうとしていたらなぜかZettelkastenとかいうものに出会っていました。
この記事はZettelkastenで思考整理した結果のアウトプットです。

てなわけで近日中に「Zettelkastenはいいぞ」の記事が出ます。
対戦よろしくお願いします。