code-review-excellence

コードレビューの質を高める

建設的なフィードバック、体系的な分析、協力による改善を通じて、コードレビューを門番の役割から知識共有の場へと変えます。

このスキルを使用する場面

• プルリクエストやコード変更をレビューするとき
• チームのコードレビュー基準を定めるとき
• レビューを通じてジュニア開発者を指導するとき
• アーキテクチャレビューを実施するとき
• レビューチェックリストやガイドラインを作成するとき
• チームのコラボレーションを改善するとき
• コードレビューのサイクル時間を短縮するとき
• コード品質の基準を維持するとき

基本原則

1. レビューに臨む姿勢

コードレビューの目的：

• バグやエッジケースを見つける
• コードの保守性を確保する
• チーム内で知識を共有する
• コーディング規約を徹底する
• 設計とアーキテクチャを改善する
• チーム文化を育む

目的ではないこと：

• 知識をひけらかす
• 書式を細かく指摘する（リンターを使いましょう）
• 不必要に進捗を妨げる
• 自分の好みに合わせて書き直す

2. 効果的なフィードバック

良いフィードバックとは：

• 具体的で、実行に移せる
• 批判的ではなく、学びにつながる
• 人ではなく、コードに焦点を当てる
• バランスが取れている（良い仕事も称賛する）
• 優先順位が明確である（重大な問題と、あると望ましい改善を区別する）

❌ Bad: "This is wrong."
✅ Good: "This could cause a race condition when multiple users
         access simultaneously. Consider using a mutex here."

❌ Bad: "Why didn't you use X pattern?"
✅ Good: "Have you considered the Repository pattern? It would
         make this easier to test. Here's an example: [link]"

❌ Bad: "Rename this variable."
✅ Good: "[nit] Consider `userCount` instead of `uc` for
         clarity. Not blocking if you prefer to keep it."

3. レビューの対象範囲

レビューする項目：

• ロジックの正しさとエッジケース
• セキュリティの脆弱性
• パフォーマンスへの影響
• テストの網羅性と品質
• エラー処理
• ドキュメントとコメント
• API の設計と命名
• アーキテクチャとの適合性

手作業でレビューしなくてよい項目：

• コードの書式（Prettier、Black などを使いましょう）
• インポートの整理
• リント違反
• 単純な誤字

レビュープロセス

フェーズ 1：背景情報の確認（2～3 分）

Before diving into code, understand:

1. Read PR description and linked issue
2. Check PR size (>400 lines? Ask to split)
3. Review CI/CD status (tests passing?)
4. Understand the business requirement
5. Note any relevant architectural decisions

フェーズ 2：全体的なレビュー（5～10 分）

1. **Architecture & Design**
   - Does the solution fit the problem?
   - Are there simpler approaches?
   - Is it consistent with existing patterns?
   - Will it scale?

2. **File Organization**
   - Are new files in the right places?
   - Is code grouped logically?
   - Are there duplicate files?

3. **Testing Strategy**
   - Are there tests?
   - Do tests cover edge cases?
   - Are tests readable?

フェーズ 3：行ごとのレビュー（10～20 分）

For each file:

1. **Logic & Correctness**
   - Edge cases handled?
   - Off-by-one errors?
   - Null/undefined checks?
   - Race conditions?

2. **Security**
   - Input validation?
   - SQL injection risks?
   - XSS vulnerabilities?
   - Sensitive data exposure?

3. **Performance**
   - N+1 queries?
   - Unnecessary loops?
   - Memory leaks?
   - Blocking operations?

4. **Maintainability**
   - Clear variable names?
   - Functions doing one thing?
   - Complex code commented?
   - Magic numbers extracted?

フェーズ 4：まとめと判断（2～3 分）

1. Summarize key concerns
2. Highlight what you liked
3. Make clear decision:
   - ✅ Approve
   - 💬 Comment (minor suggestions)
   - 🔄 Request Changes (must address)
4. Offer to pair if complex

レビュー手法

手法 1：チェックリスト方式

## Security Checklist
- [ ] User input validated and sanitized
- [ ] SQL queries use parameterization
- [ ] Authentication/authorization checked
- [ ] Secrets not hardcoded
- [ ] Error messages don't leak info

## Performance Checklist
- [ ] No N+1 queries
- [ ] Database queries indexed
- [ ] Large lists paginated
- [ ] Expensive operations cached
- [ ] No blocking I/O in hot paths

## Testing Checklist
- [ ] Happy path tested
- [ ] Edge cases covered
- [ ] Error cases tested
- [ ] Test names are descriptive
- [ ] Tests are deterministic

手法 2：質問方式

問題点を断定するのではなく、考えを促す質問をします。

❌ "This will fail if the list is empty."
✅ "What happens if `items` is an empty array?"

❌ "You need error handling here."
✅ "How should this behave if the API call fails?"

❌ "This is inefficient."
✅ "I see this loops through all users. Have we considered
    the performance impact with 100k users?"

手法 3：命令ではなく提案する

## Use Collaborative Language

❌ "You must change this to use async/await"
✅ "Suggestion: async/await might make this more readable:
    ```typescript
    async function fetchUser(id: string) {
        const user = await db.query('SELECT * FROM users WHERE id = ?', id);
        return user;
    }
    ```
    What do you think?"

❌ "Extract this into a function"
✅ "This logic appears in 3 places. Would it make sense to
    extract it into a shared utility function?"

手法 4：深刻度を区別する

Use labels to indicate priority:

🔴 [blocking] - Must fix before merge
🟡 [important] - Should fix, discuss if disagree
🟢 [nit] - Nice to have, not blocking
💡 [suggestion] - Alternative approach to consider
📚 [learning] - Educational comment, no action needed
🎉 [praise] - Good work, keep it up!

Example:
"🔴 [blocking] This SQL query is vulnerable to injection.
 Please use parameterized queries."

"🟢 [nit] Consider renaming `data` to `userData` for clarity."

"🎉 [praise] Excellent test coverage! This will catch edge cases."

言語別のパターン

Python のコードレビュー

# Check for Python-specific issues

# ❌ Mutable default arguments
def add_item(item, items=[]):  # Bug! Shared across calls
    items.append(item)
    return items

# ✅ Use None as default
def add_item(item, items=None):
    if items is None:
        items = []
    items.append(item)
    return items

# ❌ Catching too broad
try:
    result = risky_operation()
except:  # Catches everything, even KeyboardInterrupt!
    pass

# ✅ Catch specific exceptions
try:
    result = risky_operation()
except ValueError as e:
    logger.error(f"Invalid value: {e}")
    raise

# ❌ Using mutable class attributes
class User:
    permissions = []  # Shared across all instances!

# ✅ Initialize in __init__
class User:
    def __init__(self):
        self.permissions = []

TypeScript/JavaScript のコードレビュー

// Check for TypeScript-specific issues

// ❌ Using any defeats type safety
function processData(data: any) {  // Avoid any
    return data.value;
}

// ✅ Use proper types
interface DataPayload {
    value: string;
}
function processData(data: DataPayload) {
    return data.value;
}

// ❌ Not handling async errors
async function fetchUser(id: string) {
    const response = await fetch(`/api/users/${id}`);
    return response.json();  // What if network fails?
}

// ✅ Handle errors properly
async function fetchUser(id: string): Promise<User> {
    try {
        const response = await fetch(`/api/users/${id}`);
        if (!response.ok) {
            throw new Error(`HTTP ${response.status}`);
        }
        return await response.json();
    } catch (error) {
        console.error('Failed to fetch user:', error);
        throw error;
    }
}

// ❌ Mutation of props
function UserProfile({ user }: Props) {
    user.lastViewed = new Date();  // Mutating prop!
    return <div>{user.name}</div>;
}

// ✅ Don't mutate props
function UserProfile({ user, onView }: Props) {
    useEffect(() => {
        onView(user.id);  // Notify parent to update
    }, [user.id]);
    return <div>{user.name}</div>;
}

高度なレビューパターン

パターン 1：アーキテクチャレビュー

When reviewing significant changes:

1. **Design Document First**
   - For large features, request design doc before code
   - Review design with team before implementation
   - Agree on approach to avoid rework

2. **Review in Stages**
   - First PR: Core abstractions and interfaces
   - Second PR: Implementation
   - Third PR: Integration and tests
   - Easier to review, faster to iterate

3. **Consider Alternatives**
   - "Have we considered using [pattern/library]?"
   - "What's the tradeoff vs. the simpler approach?"
   - "How will this evolve as requirements change?"

パターン 2：テスト品質のレビュー

// ❌ Poor test: Implementation detail testing
test('increments counter variable', () => {
    const component = render(<Counter />);
    const button = component.getByRole('button');
    fireEvent.click(button);
    expect(component.state.counter).toBe(1);  // Testing internal state
});

// ✅ Good test: Behavior testing
test('displays incremented count when clicked', () => {
    render(<Counter />);
    const button = screen.getByRole('button', { name: /increment/i });
    fireEvent.click(button);
    expect(screen.getByText('Count: 1')).toBeInTheDocument();
});

// Review questions for tests:
// - Do tests describe behavior, not implementation?
// - Are test names clear and descriptive?
// - Do tests cover edge cases?
// - Are tests independent (no shared state)?
// - Can tests run in any order?

パターン 3：セキュリティレビュー

## Security Review Checklist

### Authentication & Authorization
- [ ] Is authentication required where needed?
- [ ] Are authorization checks before every action?
- [ ] Is JWT validation proper (signature, expiry)?
- [ ] Are API keys/secrets properly secured?

### Input Validation
- [ ] All user inputs validated?
- [ ] File uploads restricted (size, type)?
- [ ] SQL queries parameterized?
- [ ] XSS protection (escape output)?

### Data Protection
- [ ] Passwords hashed (bcrypt/argon2)?
- [ ] Sensitive data encrypted at rest?
- [ ] HTTPS enforced for sensitive data?
- [ ] PII handled according to regulations?

### Common Vulnerabilities
- [ ] No eval() or similar dynamic execution?
- [ ] No hardcoded secrets?
- [ ] CSRF protection for state-changing operations?
- [ ] Rate limiting on public endpoints?

難しいフィードバックの伝え方

パターン：サンドイッチ方式（改良版）

Traditional: Praise + Criticism + Praise (feels fake)

Better: Context + Specific Issue + Helpful Solution

Example:
"I noticed the payment processing logic is inline in the
controller. This makes it harder to test and reuse.

[Specific Issue]
The calculateTotal() function mixes tax calculation,
discount logic, and database queries, making it difficult
to unit test and reason about.

[Helpful Solution]
Could we extract this into a PaymentService class? That
would make it testable and reusable. I can pair with you
on this if helpful."

意見が合わない場合の対応

When author disagrees with your feedback:

1. **Seek to Understand**
   "Help me understand your approach. What led you to
    choose this pattern?"

2. **Acknowledge Valid Points**
   "That's a good point about X. I hadn't considered that."

3. **Provide Data**
   "I'm concerned about performance. Can we add a benchmark
    to validate the approach?"

4. **Escalate if Needed**
   "Let's get [architect/senior dev] to weigh in on this."

5. **Know When to Let Go**
   If it's working and not a critical issue, approve it.
   Perfection is the enemy of progress.

ベストプラクティス

1. 速やかにレビューする：24 時間以内、理想的には当日中に行います
2. PR の規模を抑える：効果的にレビューできるよう、最大 200～400 行にします
3. 時間を区切ってレビューする：最大 60 分にし、休憩を取ります
4. レビューツールを使う：GitHub、GitLab、または専用ツールを使います
5. 自動化できることは自動化する：リンター、フォーマッター、セキュリティスキャンを活用します
6. 信頼関係を築く：絵文字、称賛、共感が大切です
7. いつでも相談に乗る：複雑な問題はペアで取り組むことを提案します
8. 他の人から学ぶ：他の人のレビューコメントを確認します

よくある落とし穴

• 完璧主義：些細なスタイルの好みを理由に PR をブロックする
• 範囲の拡大：「ついでに、これもお願いできますか……」
• 一貫性のなさ：人によって異なる基準を適用する
• レビューの遅れ：PR を何日も放置する
• 音信不通：変更を依頼した後、連絡を絶つ
• 形式的な承認：実際にレビューせず承認する
• 些末な議論：重要でない詳細について延々と議論する

テンプレート

PR レビューコメントのテンプレート

## Summary
[Brief overview of what was reviewed]

## Strengths
- [What was done well]
- [Good patterns or approaches]

## Required Changes
🔴 [Blocking issue 1]
🔴 [Blocking issue 2]

## Suggestions
💡 [Improvement 1]
💡 [Improvement 2]

## Questions
❓ [Clarification needed on X]
❓ [Alternative approach consideration]

## Verdict
✅ Approve after addressing required changes

リソース

• references/code-review-best-practices.md：包括的なレビューガイドライン
• references/common-bugs-checklist.md：言語別の注意すべきバグ
• references/security-review-guide.md：セキュリティに重点を置いたレビューチェックリスト
• assets/pr-review-template.md：標準的なレビューコメントのテンプレート
• assets/review-checklist.md：簡易参照用チェックリスト
• scripts/pr-analyzer.py：PR の複雑さを分析し、レビュアーを提案します