Code Review Guide

🔍 A comprehensive code review guide with 26 issue categories, helping teams systematically identify and classify code problems.

📦 This is a GitHub Template Repository - Click "Use this template" to create your own code review setup!

📚 Documentation

Document	Description
CODE_REVIEW_GUIDE_EN.md	Complete review guide (English)
CODE_REVIEW_GUIDE_CN.md	Complete review guide (中文)
copilot-instructions.md	GitHub Copilot instructions (English)
copilot-instructions-cn.md	GitHub Copilot instructions (中文)
gemini-instructions.md	Gemini Code Review instructions (English)
gemini-instructions-cn.md	Gemini Code Review instructions (中文)

🚀 Quick Start

Option 1: Use as GitHub Template (Recommended)

1. Click the green "Use this template" button at the top of this repository
2. Select "Create a new repository"
3. Your new repository will include all configurations automatically
4. Done! AI Code Review is now enabled for your project

Option 2: Copy to Existing Project

# Clone this repository
git clone https://github.com/pubgo/codereview.git

# Copy the .github folder to your project
cp -r codereview/.github /path/to/your/project/

# Optional: Copy the full guides
mkdir -p /path/to/your/project/docs
cp -r codereview/docs/codereview /path/to/your/project/docs/

Option 3: Cherry-pick Specific Files

# Only Copilot support
curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/pubgo/codereview/main/.github/copilot-instructions.md

# Only Gemini support  
curl -o .github/gemini-instructions.md https://raw.githubusercontent.com/pubgo/codereview/main/.github/gemini-instructions.md
curl -o .github/gemini.json https://raw.githubusercontent.com/pubgo/codereview/main/.github/gemini.json

# Only PR template
curl -o .github/PULL_REQUEST_TEMPLATE.md https://raw.githubusercontent.com/pubgo/codereview/main/.github/PULL_REQUEST_TEMPLATE.md

---

🔄 How It Works

PR Workflow

┌──────────────────────────────────────────────────────────┐
│  1. Developer creates a Pull Request                     │
└──────────────────────────────┬───────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────┐
│  2. PR Template auto-fills with checklist                │
│     ─ PULL_REQUEST_TEMPLATE.md                           │
└──────────────────────────────┬───────────────────────────┘
                               │
               ┌───────────────┼───────────────┐
               ▼               ▼               ▼
┌────────────────┐ ┌───────────────┐ ┌───────────────┐
│ 3a. Copilot    │ │ 3b. Gemini    │ │ 3c. Human     │
│ Auto-Review    │ │ Auto-Review   │ │ Review        │
│                │ │               │ │               │
│ Reads:         │ │ Reads:        │ │ References:   │
│ copilot-       │ │ gemini-       │ │ CODE_REVIEW   │
│ instructions   │ │ instructions  │ │ _GUIDE.md     │
└────────────────┘ └───────────────┘ └───────────────┘
               │               │               │
               └───────────────┼───────────────┘
                               ▼
┌──────────────────────────────────────────────────────────┐
│  4. Review comments with issue categories                │
│     [LOGI] [SEC] [PERF] [DSN] ...                        │
└──────────────────────────────────────────────────────────┘

GitHub Copilot Integration

Copilot automatically reads .github/copilot-instructions.md when reviewing your code.

In VS Code / GitHub:

# Ask Copilot to review:
"Please review this code"
"Check this PR for issues"
"What problems do you see in this function?"

Enable Copilot Code Review in Repository:

1. Go to Repository Settings → Code review → Copilot
2. Enable "Copilot code review"
3. Copilot will automatically review new PRs

Gemini Code Assist Integration

Gemini uses .github/gemini.json for configuration and .github/gemini-instructions.md for review guidelines.

Setup Options:

Method	Configuration
GitHub App	Install Gemini Code Assist from Marketplace
Google AI Studio	Copy gemini-instructions.md content to System Instructions
Gemini API	Use as system prompt in API calls
IDE Extensions	Configure as custom instructions

For Human Reviewers

1. Open the guide: CODE_REVIEW_GUIDE_EN.md

2. Use the checklist: Go through each category systematically

3. Label issues with category codes:

   [LOGI] Null pointer not checked before accessing user.name
   [SEC] SQL query directly concatenates user input
   [PERF] Database query inside loop should use batch query
   

---

🎯 Customization

Adjust for Your Project

1. Modify Priority Levels: Edit the instructions files to match your team's priorities
2. Add Project-specific Checks: Extend the checklist with domain-specific items
3. Integrate with CI/CD: Use the issue categories in automated pipelines

Language Selection

Language	Copilot	Gemini	Guide
English	copilot-instructions.md	gemini-instructions.md	CODE_REVIEW_GUIDE_EN.md
中文	copilot-instructions-cn.md	gemini-instructions-cn.md	CODE_REVIEW_GUIDE_CN.md

📋 Issue Categories Overview

Priority Levels

Priority	Icon	Description	Categories
Critical	🔴	Must fix	REQ, LOGI, SEC, AUTH
High	🟠	Strongly recommend fixing	DSN, RBST, TRANS, CONC, PERF
Medium	🟡	Should fix	CPT, IDE, MAIN, CPL
Normal	🟢	Can improve	READ, SIMPL, CONS, DUP, NAM, DOCS
Low	🔵	Nice to have	COMM, LOGG, ERR, FOR, GRAM, PRAC, PR

Category Quick Reference

Code	Category	Priority	Description
REQ	Requirements Unmatch	🔴	Implementation doesn't match requirements
LOGI	Logic Issues	🔴	Bugs preventing correct execution
SEC	Security	🔴	Vulnerabilities and security risks
AUTH	Authentication/Authorization	🔴	Access control issues
DSN	Design	🟠	Architectural and design problems
RBST	Robustness	🟠	Error handling and fault tolerance
TRANS	Transaction	🟠	Database transaction issues
CONC	Concurrency	🟠	Multi-threading problems
PERF	Performance	🟠	Resource efficiency issues
CPT	Compatibility	🟡	Version and environment compatibility
IDE	Idempotence	🟡	Repeated operation safety
MAIN	Maintainability	🟡	Long-term maintenance concerns
CPL	Coupling	🟡	Module interdependencies
READ	Readability	🟢	Code clarity issues
SIMPL	Simplicity	🟢	Unnecessary complexity
CONS	Consistency	🟢	Style and naming consistency
DUP	Duplication	🟢	Repeated code/logic
NAM	Naming	🟢	Variable/function naming
DOCS	Doc String	🟢	Documentation comments
COMM	Comments	🔵	Inline comments
LOGG	Logging	🔵	Log statements
ERR	Error Messages	🔵	Error definitions
FOR	Format	🔵	Code formatting
GRAM	Grammar	🔵	Text grammar issues
PRAC	Best Practice	🔵	Convention violations
PR	PR Description	🔵	PR documentation

💡 Golden Rules

1. Simple, Efficient, Secure Design - Avoid over-engineering; prioritize clarity and security
2. Strict Integrity & Performance - Ensure data integrity and optimize where needed
3. Proper Modulation - High cohesion within modules, low coupling between them
4. Minimize Repetition - DRY principle (Don't Repeat Yourself)
5. Good Naming & Comments - Clear, descriptive names; meaningful comments

Review Benchmark

Target: Find at least 1 logic issue per 100 lines of code (LOC)

🛠️ Integration

VS Code + GitHub Copilot

1. Ensure .github/copilot-instructions.md exists in your repo
2. Open VS Code with GitHub Copilot extension installed
3. Ask Copilot to review code - it will follow the guidelines automatically

PR Template Integration

# .github/PULL_REQUEST_TEMPLATE.md

## Pre-submission Checklist

- [ ] Self-review completed
- [ ] No critical issues ([REQ], [LOGI], [SEC], [AUTH])
- [ ] Performance considered ([PERF])
- [ ] Tests added/updated

Supported Platforms

• GitHub Pull Request Reviews
• GitLab Merge Request Reviews
• Gerrit Code Reviews
• Bitbucket Code Reviews
• Any code review platform

📁 Repository Structure

. ├── .github/ │ ├── ISSUE_TEMPLATE/ # Issue templates │ │ ├── bug_report.md │ │ ├── feature_request.md │ │ └── config.yml │ ├── CONTRIBUTING.md # Contributing guide │ ├── PULL_REQUEST_TEMPLATE.md # PR template with checklist │ ├── copilot-code-review.yml # Copilot auto-review config │ ├── copilot-instructions-cn.md # GitHub Copilot instructions (中文) │ ├── copilot-instructions.md # GitHub Copilot instructions (English) │ ├── gemini-instructions-cn.md # Gemini instructions (中文) │ ├── gemini-instructions.md # Gemini instructions (English) │ └── gemini.json # Gemini auto-review config ├── docs/ │ └── codereview/ │ ├── CODE_REVIEW_GUIDE_CN.md # Full guide (中文) │ └── CODE_REVIEW_GUIDE_EN.md # Full guide (English) ├── README.md # This file (English) ├── README_CN.md # Chinese README └── LICENSE

🤝 Contributing

Contributions are welcome! Feel free to:

• Add new issue categories
• Improve existing checklists
• Add examples for specific languages/frameworks
• Translate to other languages
• Share your experience and feedback

📖 References

• Google Code Review Guidelines
• The Code Review Pyramid

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ for better code quality