建設的なコメントの書き方

ストーリー

あなた

チェックリストに沿ってレビューしたんですが、コメントを書くときに悩むんです…。指摘したいけど、きつく聞こえないか心配で

あ

松本先輩が笑顔で答えた。

佐

佐藤先輩

その気持ちは大事だ。レビューコメントは『何を言うか』と同じくらい『どう言うか』が重要なんだ。同じ指摘でも、書き方ひとつで受け取り方が全然違う。建設的なコメントの書き方を一緒に学んでいこう

レビューコメントの基本原則

1. 具体的に書く

曖昧な指摘は改善につながりません。

❌ 曖昧:
「このコードは良くないです」
「もう少し改善してください」

✅ 具体的:
「この関数は30行を超えており、読みにくくなっています。
 バリデーション部分を別関数に切り出すことを提案します」

「変数名 `d` が何を表すか分かりにくいです。
 `deliveryDate` のように意図が分かる名前にしませんか？」

2. 理由を添える

「なぜ」を説明することで、相手の理解と成長を促します。

❌ 理由なし:
「ここは async/await を使ってください」

✅ 理由あり:
「ここは async/await を使うことを提案します。
 .then() チェーンが3段以上ネストしており、
 async/await にすることで処理の流れが上から下に
 読めるようになり、エラーハンドリングも
 try/catch で統一できます」

3. 提案形式で書く

命令ではなく提案として書くことで、対話が生まれます。

❌ 命令形:
「ここを修正しろ」
「これは間違いです」

✅ 提案形:
「ここは〇〇にすると、△△のメリットがあると思います。いかがでしょうか？」
「〇〇というアプローチも考えられますが、どう思いますか？」

コメントのプレフィックス規約

チームで統一したプレフィックスを使うことで、コメントの意図が明確になります。

プレフィックス	意味	対応
`[Must Fix]`	必須修正（バグ・セキュリティ）	マージ前に必ず修正
`[Should Fix]`	推奨修正（品質改善）	可能であれば修正
`[Nit]`	些細な指摘	修正は任意
`[Question]`	質問・確認	回答をお願い
`[Praise]`	良い点の評価	対応不要
`[FYI]`	参考情報の共有	対応不要

実際の使用例

// ファイル: src/services/orderService.ts

// --- コメント1 ---
// [Must Fix] orderItems が空配列の場合、
// totalAmount が 0 になりますが、0円の注文は
// ビジネスロジックとして許容されますか？
// 空の場合はエラーにすべきだと思います。
async function createOrder(orderItems: OrderItem[]) {
  const totalAmount = orderItems.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  );
  // ...
}

// --- コメント2 ---
// [Should Fix] この定数はここにハードコードするよりも、
// 設定ファイルに移すことを提案します。
// 将来、税率が変更された際の修正が容易になります。
const TAX_RATE = 0.10;

// --- コメント3 ---
// [Nit] `calc` よりも `calculateTotalWithTax` の方が
// 関数の意図が伝わりやすいと思います。
function calc(amount: number): number {
  return amount * (1 + TAX_RATE);
}

// --- コメント4 ---
// [Praise] エラーハンドリングが丁寧で、
// 各エラーケースに適切なエラーメッセージが設定されています。
// この品質をぜひ維持してください。

// --- コメント5 ---
// [Question] この並び替えは注文日時の降順で合っていますか？
// 仕様書では「最新の注文が上」とありますが、
// ここは昇順になっているように見えます。
const sorted = orders.sort((a, b) =>
  a.createdAt.getTime() - b.createdAt.getTime()
);

// --- コメント6 ---
// [FYI] TypeScript 5.0 以降では `satisfies` 演算子が使えるので、
// 型推論を維持しながら型チェックができます。
// 参考: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html

コメントの悪い例と良い例

パターン1: 曖昧な否定 → 具体的な提案

❌ 「このコードは読みにくい」

✅ 「[Should Fix] この関数は3つの異なる責務を持っています:
    (1) バリデーション、(2) データ変換、(3) DB保存。
    それぞれを別関数に分割すると、テストしやすく
    読みやすくなると思います。
    例えば:
    - validateOrderInput(input)
    - transformToOrder(validatedInput)
    - saveOrder(order)
    のように分けてはどうでしょうか？」

パターン2: 上から目線 → 対等な対話

❌ 「なぜ for ループを使っているんですか？
    map を知らないのですか？」

✅ 「[Nit] ここは Array.map() を使うと、
    変換処理であることがより明確になると思います:

    const names = users.map(user => user.name);

    for ループとの違いは、map は『各要素を変換して
    新しい配列を作る』という意図を宣言的に表せる点です。
    ただ、パフォーマンス上の理由でfor を選んでいる
    場合はこのままで問題ありません」

パターン3: 感情的な反応 → 客観的な説明

❌ 「こんなバグを見逃すなんて信じられない」

✅ 「[Must Fix] この条件分岐で、userRole が undefined の
    場合に意図しない分岐に入る可能性があります。
    具体的には、ログインしていないユーザーが
    管理者ページにアクセスできてしまいます。

    以下のように null チェックを追加することを提案します:
    if (userRole != null && userRole === 'admin') { ... }」

コメントの書き方テンプレート

指摘コメント

[プレフィックス] 問題の説明

理由: なぜこれが問題か

提案: 具体的な改善案（コード例があるとベスト）

質問コメント

[Question] 確認したいこと

背景: なぜそう思ったか、何が疑問か

賞賛コメント

[Praise] 良い点の具体的な説明

（例: テストカバレッジ、エラーハンドリング、設計パターン）

日本語でのレビューコメント文例集

シーン	コメント例
バグの指摘	「ここは意図した動作と異なる可能性があります。〇〇の場合に△△になりませんか？」
設計の改善	「〇〇パターンを使うと、この部分がよりシンプルになると思います。いかがでしょうか？」
テスト追加	「このケースのテストも追加していただけると、安心してマージできます」
命名の改善	「〇〇という名前にすると、この変数の役割がより伝わると思います」
良い点	「このエラーハンドリングの設計、とても参考になります」
確認	「この仕様について確認したいのですが、〇〇という理解で合っていますか？」

まとめ

項目	ポイント
基本原則	具体的に・理由を添えて・提案形式で
プレフィックス	Must Fix / Should Fix / Nit / Question / Praise / FYI
避けるべきこと	曖昧な否定、上から目線、感情的な反応
心がけ	1つのPRに最低1つは Praise を入れる

チェックリスト

レビューコメントの3つの基本原則を実践できる
プレフィックス規約を使い分けられる
悪い例を良い例に書き換えられる
建設的なコメントのテンプレートを使える
賞賛コメントを意識的に書ける

次のステップへ

コメントの書き方を学んだら、次はレビューを効率化するツールの活用方法を見ていきます。GitHub PRやVS Codeの機能を使いこなして、レビューの生産性を上げましょう。

推定読了時間: 25分