コードレビューのコメント例60｜ラベル別の書き方と言い換え表

伝わるレビューコメントは、先頭のラベルで「対応が必須かどうか」を示し、本文に「事実・理由・提案」の3つを書いたものです。 この形にそろえると、受け取った人は何をどこまで直せばよいかを1回で判断でき、確認のやり取りが減ります。

この記事は、レビューの「観点」ではなくコメントの「文面」に絞っています。ラベル別×観点別の例文60本（Markdown表とタブ区切りの両方）、国内でよく使われるプレフィックスと Google・Conventional Comments のラベル対応表、伝わりにくいコメントを直した言い換え表20組、対応必須かどうかの判断表、定型コメントの登録用ひな形、チームのレビュー規約（REVIEW.md）のテンプレート全文を載せています。何を確認するかの観点は「コードレビューの観点チェックリスト｜優先順位と伝え方」で扱っています。

確認環境：例文の表とタブ区切りデータは Ubuntu 24.04・Python 3.11.15 で1つのデータから生成し、60行×4列であることを確かめています。ラベルの定義と GitHub・GitLab の手順は、2026年10月7日に各公式ページを開いて確認した内容です。

レビューコメントのラベル早見表

コメントの基本形は「ラベル＋事実・理由・提案」

1つのコメントに次の3つが入っていると、読んだ人がそのまま動けます。

そのまま貼って使える型です。

[ラベル] （事実）〜になっています。
（理由）〜のため／〜の場合に〜になります。
（提案）〜してください／〜にしませんか／〜でしょうか。

Google が公開しているレビューの手引き「How to write code review comments」でも、親切であること、理由を説明することが要点として挙げられ、人ではなくコードについて書くことが勧められています。同じページには、良い点を見つけたら伝えること、説明が必要なコードはレビュー欄で説明してもらうのではなくコード自体を分かりやすく直してもらうこと、も書かれています。

ラベルの対応表（国内のプレフィックス・Google・Conventional Comments）

ラベルの呼び方はチームや資料によって違いますが、伝えたい意図は共通しています。自分のチームのラベルが、他の流儀のどれに当たるかを1枚にまとめました。

それぞれの出どころは次のとおりです。

Conventional Comments の9ラベルと3つの装飾

Conventional Comments のサイトでは、装飾を付けないときの既定を「止めない」にする組織と「止める」にする組織の両方がある、と説明されています。どちらにするかをチームで決めて、規約に1行書いておくと迷いません。

対応必須かどうかを決める判断表

ラベルで迷うのは、ほとんどが must と should の境目です。「マージした後に利用者やデータに影響が出るか」で分けると判断がそろいます。

迷ったら [ask] で意図を聞き、返信を見てからラベルを決めると、必須の指摘が増えすぎることを防げます。

ラベル別×観点別のコメント例文60本

命名・設計・テスト・セキュリティ・性能・可読性の6観点に、10本ずつ並べています。各観点の内訳は [must] 2本、[should] 2本、[imo] 1本、[nits] 1本、[ask] 2本、[info] 1本、[praise] 1本です。クラス名や数値は例なので、自分のコードに合わせて置き換えてください。

命名のコメント例（10本）

設計のコメント例（10本）

テストのコメント例（10本）

セキュリティのコメント例（10本）

性能のコメント例（10本）

可読性のコメント例（10本）

タブ区切り版（表計算ソフトや定型文の管理表に貼る用）

上の60本と同じ内容です。列は「No・ラベル・観点・コメント」の4つで、タブで区切っています。

No  ラベル 観点  コメント
1   [must]  命名  `getUser()` が登録処理も行っています。呼び出す側は「取得だけ」と読むため、登録を `registerUser()` に分けるか、名前を `getOrCreateUser()` にしてください。
2   [must]  命名  定数 `MAX` が「1ページの件数」と「再試行の回数」の2か所で使われています。片方を変えるともう片方も変わるため、`PAGE_SIZE` と `MAX_RETRY` に分けてください。
3   [should]    命名  `data` `list2` は中身が名前から読み取れません。`overdueItems`（返却期限を過ぎた備品）のように、入っているものを名前にしませんか。
4   [should]    命名  真偽値 `flag` は true のときの意味が読み取れません。`isArchived` のように is／has で始めると、if 文がそのまま文章として読めます。
5   [imo]   命名  `calc()` は `calcSubtotal()` の方が、合計との違いが伝わりやすいと感じました。判断はお任せします。
6   [nits]  命名  `recieve` → `receive` の typo です。検索で見つけにくくなるので、同じつづりの3か所もあわせてお願いします。
7   [ask]   命名  `tmpId` と `draftId` は同じものを指していますか。別のものなら、違いが分かるコメントがあると助かります。
8   [ask]   命名  単位は秒とミリ秒のどちらでしょうか。`timeout` を `timeoutMs` にすると、呼び出す側で迷わなくなりそうです。
9   [info]  命名  このリポジトリでは、DBの列名は snake_case、コード上は camelCase にそろえています（docs/naming.md）。今回の修正は不要で、次回からの参考です。
10  [praise]    命名  `isReturnable` という名前のおかげで、条件式を読まなくても意図が分かりました。同じ付け方を他の判定にも広げたいです。
11  [must]  設計  コントローラーから直接SQLを実行しています。同じ検索が3か所に増えているため、`ItemRepository` に移して1か所にまとめてください。
12  [must]  設計  この変更で `OrderService` と `StockService` が互いを呼び合う形になります。初期化の順序によって起動時にエラーになるため、在庫の引き当てを別クラスに切り出してください。
13  [should]    設計  1つのメソッドで「入力チェック・保存・メール送信」を行っています。メール送信を分けると、保存だけのテストが書きやすくなります。
14  [should]    設計  種別ごとの if が4段になっています。種別が増えるたびに分岐が増えるため、種別ごとのクラス（または辞書）に分けませんか。
15  [imo]   設計  設定値を引数で受け取る形にすると、テストで差し替えやすくなると思います。今回の範囲を超えるなら別のPRで構いません。
16  [nits]  設計  この private メソッドは1か所からしか呼ばれておらず、3行です。呼び出し元に戻しても読みやすさは変わらなさそうです。
17  [ask]   設計  キャッシュを使わず毎回取得する形にしたのは、鮮度を優先したためでしょうか。背景をPRの説明に残してもらえると、後から読む人が助かります。
18  [ask]   設計  この処理が途中で止まった場合、再実行しても二重登録になりませんか。想定を教えてください。
19  [info]  設計  同じ目的の共通関数が `utils/paging.py` にあります。今回はこのままで問題なく、次に触るときの参考にどうぞ。
20  [praise]    設計  外部APIの呼び出しをインターフェースの裏に置いたことで、テストがネットワークなしで動くようになっています。変更にも強い形だと思います。
21  [must]  テスト 件数0件のケースのテストがありません。画面は空配列が返る前提で作られているため、0件のときの期待値を1本追加してください。
22  [must]  テスト このテストは現在時刻に依存していて、月末に実行すると結果が変わります。時刻を引数か固定値で渡す形にしてください。
23  [should]    テスト 1つのテストで5つの検証をしています。最初の検証で止まると残りの結果が分からないため、検証ごとに分けませんか。
24  [should]    テスト 境界値（上限ちょうど、上限+1）のテストがあると、条件の `<` と `<=` の取り違えに気づけます。
25  [imo]   テスト テスト名を「何をしたら・どうなる」の形（例：`期限切れなら貸出不可`）にすると、失敗したときに原因が一目で分かると思います。
26  [nits]  テスト テストデータの `aaa` `test1` は、`期限切れの備品` のように意味のある値にすると読みやすくなります。
27  [ask]   テスト 異常系（DB接続エラー時）は、別のテストで確認済みでしょうか。場所を教えてもらえれば見に行きます。
28  [ask]   テスト モックが返す値と本物のAPIの返り値の形は、どこかで突き合わせていますか。
29  [info]  テスト 一覧系のテストは `tests/factories.py` のファクトリを使うと、データの準備が1行になります。今回の修正は不要です。
30  [praise]    テスト 並び替えのテストに「同じ値が並んだとき」のケースまで入っていて、順序が安定することが確認できました。
31  [must]  セキュリティ  文字列連結でSQLを組み立てています。入力値がそのままSQLの一部として解釈されるため、プレースホルダー（`WHERE id = %s` と引数）に変えてください。
32  [must]  セキュリティ  他の会員のIDを指定すると、その会員の注文が取得できます。`user_id = ログイン中の会員ID` の条件を追加してください。
33  [should]    セキュリティ  エラー応答にスタックトレースがそのまま入っています。内部のファイル構成が外から見えるため、利用者には定型のメッセージ、詳細はログ、と分けませんか。
34  [should]    セキュリティ  トークンをログに出力しています。ログを見られる人全員が使える状態になるため、先頭4文字だけ残して伏せませんか。
35  [imo]   セキュリティ  利用者が入力したファイル名を、そのまま保存先のパスに使っています。サーバー側で採番した名前に置き換える方が、扱いが単純になると思います。
36  [nits]  セキュリティ  `.env.example` に本物に見える値が入っています。`changeme` などの仮の値にしておくと、取り違えがなくなります。
37  [ask]   セキュリティ  この管理用エンドポイントは、権限チェックをどの層で行っていますか。ミドルウェアで見ているなら問題ありません。
38  [ask]   セキュリティ  入力の最大長はどこで制限していますか。数MBの文字列が来た場合の動きを教えてください。
39  [info]  セキュリティ  依存ライブラリの更新は、週次の自動PRにまとめる運用です。今回のPRでバージョンを上げる必要はありません。
40  [praise]    セキュリティ  パスワードの比較に一定時間で比較する関数を使っていて、権限チェックも最初に置かれています。安心して読めました。
41  [must]  性能  ループの中で1件ずつSELECTしています。一覧が100件なら101回の問い合わせになるため、IN句かJOINで1回にまとめてください。
42  [must]  性能  全件を取得してからアプリ側で絞り込んでいます。件数が増えるとメモリを使い切るため、WHERE と LIMIT をSQL側に移してください。
43  [should]    性能  `WHERE status = ? ORDER BY created_at` の検索が追加されています。`(status, created_at)` の索引があると、並び替えまで索引で済みます。
44  [should]    性能  同じ設定値を1リクエストの中で3回読み込んでいます。最初に1回読んで渡す形にしませんか。
45  [imo]   性能  ここは件数が数十件で頭打ちなので、今の実装のままで十分だと思います。計測して遅ければ見直す、で良さそうです。
46  [nits]  性能  ループ内の `len(items)` は外で1回求めておけます。差はわずかなので、手が空いていれば、で構いません。
47  [ask]   性能  この処理の想定件数と、目標の応答時間はどのくらいでしょうか。計測結果があればPRに貼ってもらえると助かります。
48  [ask]   性能  外部APIの呼び出しにタイムアウトは設定されていますか。応答が返らない場合の動きを確認したいです。
49  [info]  性能  一覧APIの変更では、`EXPLAIN ANALYZE` の結果をPRに貼る運用にしています。次回からお願いします。
50  [praise]    性能  変更前後の計測結果（平均 480ms → 95ms）がPRに書かれていて、効果がすぐ分かりました。
51  [must]  可読性 例外を受け取ったあと何もせず `pass` にしています。処理が止まっても気づけなくなるため、ログを出すか、呼び出し元に送ってください。
52  [must]  可読性 コメントが実装と食い違っています（コメントは「30日」、コードは `14`）。どちらが正しいか確認して、そろえてください。
53  [should]    可読性 ネストが5段あります。対象外の条件を先に return する形（早期リターン）にすると、本筋が左端に並びます。
54  [should]    可読性 `86400` や `3` が直接書かれています。`SECONDS_PER_DAY` `MAX_RETRY` のような名前を付けると、意味と変更箇所が分かります。
55  [imo]   可読性 三項演算子が入れ子になっている箇所は、if 文に開いた方が読みやすいと感じました。好みの範囲です。
56  [nits]  可読性 import の順序がファイル内で混ざっています。フォーマッターを掛けるとそろいます。
57  [ask]   可読性 この `sleep(3)` は何を待っていますか。理由をコメントに1行残してもらえると助かります。
58  [ask]   可読性 この分岐に入るのは、どんな入力のときでしょうか。例をコメントかテストで示してもらえますか。
59  [info]  可読性 「なぜそうしたか」はコードコメント、「何を変えたか」はコミットメッセージ、という分け方にしています。次回からの参考です。
60  [praise]    可読性 関数が「取得・変換・出力」の3つに分かれていて、上から読むだけで流れが分かりました。レビューの時間も短く済みました。

伝わりにくいコメントの言い換え表20組

直す前のコメントは、どれも短くて書きやすいものです。そこに事実・理由・提案を足すと、受け取った人が次に何をすればよいかが分かる文面になります。

言い換えるときの置き換え早見表

GitHub の提案機能で修正案をそのまま渡す

文章で説明するより、修正案のコードを渡した方が早い場面があります。GitHub のプルリクエストには、レビューコメントから修正案を提案する機能があります。GitHub Docs の手順は次のとおりです。

受け取った側は、[提案のコミット] でその提案だけを1つのコミットとして取り込めます。複数の提案をまとめたいときは [提案をバッチに追加する] で集めてから [提案のコミット] を押します。

提案に添える文面の例です。

[should] 件数0のときに `items[0]` で例外になります。
先に空かどうかを確認する形を提案します。問題なければ、このまま取り込んでください。

（この下に、提案用アイコンで挿入した提案ブロックを置く）

GitLab での書き方

GitLab のマージリクエストでは、コメント内に次の形のコードブロックを書くと提案になります。GitLab のドキュメントに載っている記法です。

```suggestion:-0+0
修正後の行の内容をここに書く
```

-0+0 は、選んだ行から見て「上に何行・下に何行」を置き換えるかを表します。-2+2 と書くと、選んだ行の上2行と下2行を含めた範囲が対象です。GitLab のドキュメントでは、上下それぞれ100行までと説明されています。

定型コメントのひな形（Saved replies 登録用）

GitHub には、よく書く文面を登録しておく「保存済みの返信（Saved replies）」があります。GitHub Docs の作成手順は次のとおりです。

1. 右上のプロフィール写真をクリックし、Settings を開く
2. サイドバーの「Code, planning, and automation」の中の 保存済みの返信 をクリックする
3. タイトルを入力し、本文を Markdown で書く
4. 保存済み返信を追加 をクリックする

登録しておくと便利な10本です。タイトルと本文をそのまま貼れます。

タイトル：must（必須の指摘）
本文：
[must] （事実）
（理由）このままだと〜になります。
（提案）〜に変更をお願いします。

タイトル：should（推奨の指摘）
本文：
[should] （事実）
（理由）〜のため、〜にしませんか。
見送る場合は、理由を返信してもらえれば問題ありません。

タイトル：imo（意見）
本文：
[imo] 〜の方が〜だと感じました。判断はお任せします。

タイトル：nits（細かな点）
本文：
[nits] 〜です。対応は任意です。

タイトル：ask（意図の質問）
本文：
[ask] ここは〜という意図でしょうか。背景を教えてください。修正の依頼ではありません。

タイトル：info（参考情報）
本文：
[info] 参考です。〜という資料・共通関数があります（場所：）。今回の修正は不要です。

タイトル：praise（良かった点）
本文：
[praise] 〜のおかげで、〜が分かりやすかったです。

タイトル：範囲外（別PRの提案）
本文：
[info] 今回の変更の範囲を超えるので、別のPRで対応しませんか。課題票：#

タイトル：テスト追加のお願い
本文：
[should] 〜のケースのテストがありません。条件を変えているので、1本追加しませんか。
入力：／期待する結果：

タイトル：承認（Approve）
本文：
確認しました。[must] はありません。
良かった点：
任意の指摘（[imo] [nits]）は、対応してもしなくてもマージして問題ありません。

指摘を受けた側の返信例

コメントは返信まで含めて1つのやり取りです。対応した内容か、見送る理由のどちらかを必ず返すと、レビューが早く終わります。

レビュー規約（REVIEW.md）のテンプレート全文

リポジトリの直下か docs/ に置いて使えます。◯ の部分をチームの決まりに置き換えてください。

# レビュー規約（REVIEW.md）

最終更新：YYYY-MM-DD ／ 管理：◯◯チーム

## 1. 目的

- コードベースを少しずつ良くすること
- 知識をチームで共有すること
- 利用者に影響する不具合をマージ前に見つけること

## 2. 基本の考え方

- コメントは人ではなく、コードについて書く
- 指摘には理由を書く（事実 → 理由 → 提案）
- 良い点を見つけたら伝える（1回のレビューで1つ以上）
- 意図が読み取れないときは、指摘の前に質問する
- 好みの違いは [imo] か [nits] とし、マージを止めない

## 3. ラベル

| ラベル | 意味 | 対応 |
|---|---|---|
| [must] | 直さないとマージできない | 必須 |
| [should] | 直した方がよい | 原則対応。見送るときは理由を返信 |
| [imo] | 個人の意見 | 任意 |
| [nits] | 細かな点（typo・体裁） | 任意 |
| [ask] | 質問 | 返信が必要 |
| [info] | 参考情報 | 不要 |
| [praise] | 良かった点 | 不要 |

- ラベルのないコメントは [should] として扱う

## 4. [must] にする基準

- 仕様と違う動きをする、またはデータが壊れる
- 権限・入力チェックなど安全面に穴がある
- チームの規約・自動チェックに反している
- 想定件数で応答が大きく遅くなる

## 5. コメントの書き方

    [ラベル] （事実）〜になっています。
    （理由）〜のため／〜の場合に〜になります。
    （提案）〜してください／〜にしませんか。

- 修正案がはっきりしているときは、提案機能でコードを渡す
- 1つのコメントには1つの話題だけを書く
- 同じ指摘が3か所以上あるときは、1か所に書いて「他の箇所も同様です」と添える
- 議論が3往復を超えたら、通話か対面に切り替え、結論をコメントに残す

## 6. 依頼する側（書いた人）

- 1つのプルリクエストは ◯◯ 行以内を目安にする
- 説明欄に「目的・変更内容・確認方法・見てほしい点」を書く
- 自動チェック（整形・静的解析・テスト）が通ってから依頼する
- すべてのコメントに「対応した内容」か「見送る理由」を返信する
- [must] に対応したら、再レビューを依頼する

## 7. レビューする側

- 依頼から ◯ 営業時間以内に最初の返信をする
- すぐに見られないときは、いつ見られるかを返信する
- [must] が0件になったら承認する（[imo] [nits] が残っていても承認してよい）
- 承認するときは、確認した範囲を一言添える

## 8. マージの条件

- 承認 ◯ 名以上
- [must] がすべて解決している
- 自動チェックがすべて成功
- マージするのは ◯◯（書いた人／レビューした人）

## 9. 自動化に任せること

- インデント・空白・import の並び順 → フォーマッター
- 命名の形式・使っていない変数 → 静的解析
- 人のレビューでは、設計・仕様・読みやすさに時間を使う

## 10. この規約の見直し

- ◯ か月に1回、振り返りで見直す
- 変更したいときは、このファイルへのプルリクエストで提案する

よくある質問

Q. ラベルは何種類から始めるとよいですか？ A. [must]・[should]・[nits]・[ask] の4つから始めると覚えやすく、必須かどうかと質問かどうかが区別できます。慣れてきたら [imo]・[info]・[praise] を足します。種類を増やすより、[must] の基準をチームでそろえることの方が効果があります。

Q. [must] ばかりになってしまいます。どうすればよいですか？ A. 判断表の上3行（仕様・データ、安全面、規約）に当てはまるものだけを [must] にし、残りは [should] 以下にします。意図が読み取れないものは、まず [ask] で聞いてからラベルを決めます。体裁の指摘はフォーマッターと静的解析に任せると、人のコメントは大事な点に集中できます。

Q. 英語のラベル（Conventional Comments）と日本語のプレフィックスは、どちらを使うとよいですか？ A. どちらでも、チーム内で意味がそろっていれば同じように機能します。海外のメンバーや公開リポジトリとやり取りするなら Conventional Comments、国内のチームで短く書きたいなら [must] などのプレフィックスが使いやすいです。対応表を規約に貼っておくと、行き来するときに迷いません。

Q. 褒めるコメントは、わざわざ書いた方がよいですか？ A. 書くことをおすすめします。Google の手引きは良い点を伝えることを勧めており、Conventional Comments も praise を1回のレビューで少なくとも1つ残すことを勧めています。良い書き方が言葉になると、チームの他の人も同じ書き方を選びやすくなります。「何が」「なぜ良かったか」まで書くのがコツです。

まとめ

• コメントは「ラベル＋事実・理由・提案」の形にすると、受け取った人が1回で判断できる
• ラベルは「対応が必須かどうか」を伝えるためのもの。[must]・[should]・[imo]・[nits]・[ask]・[info]・[praise] の7つで足りる
• [must] にするのは、仕様・データ・安全面・規約に関わるもの。迷ったら [ask] で意図を聞く
• 国内のプレフィックス、Google の Nit／Optional／FYI、Conventional Comments の9ラベルは、意図で対応づけられる
• 伝わりにくいコメントは、人ではなくコードを主語にし、理由と提案を足すと直せる
• 修正案がはっきりしているときは提案機能、よく書く文面は保存済みの返信に任せる
• ラベルの意味と [must] の基準を REVIEW.md に書いておくと、人によるばらつきが減る

参考・出典（確認日：2026年10月7日）

• Google Engineering Practices「How to write code review comments」 https://google.github.io/eng-practices/review/reviewer/comments.html
• Conventional Comments https://conventionalcomments.org/
• GitHub Docs（pull request へのコメント） https://docs.github.com/ja/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request
• GitHub Docs（提案された変更の取り込み） https://docs.github.com/ja/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request
• GitHub Docs（保存済みの返信の作成） https://docs.github.com/ja/get-started/writing-on-github/working-with-saved-replies/creating-a-saved-reply
• GitLab Docs（マージリクエストでの変更の提案） https://docs.gitlab.com/user/project/merge_requests/reviews/suggestions/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。