Code Reviews

Code reviews are a critical practice for maintaining code quality, sharing knowledge, and building team cohesion. This section covers the complete code review process from the Microsoft Engineering Playbook.

Why Code Reviews?

Code reviews serve three primary purposes:

1. Improve code quality by catching defects early
2. Facilitate learning through exposure to different patterns and approaches
3. Build shared understanding across the development team

Peer code reviews on every pull request (or check-in to a shared branch) should be standard practice, with reviews functioning as collaborative conversations rather than gatekeeping mechanisms.

Core Principles

Quality Over Speed

• Don't rush reviews
• Catch issues before they reach production
• Reviews are an investment, not overhead

Collaborative, Not Adversarial

• Reviews are conversations, not critiques
• Focus on the code, not the person
• Assume good intent

Learning Opportunity

• Share knowledge through reviews
• Explain the "why" behind suggestions
• Welcome questions

Topics in This Section

Pull Request Process

How to create and manage effective pull requests:

• Author responsibilities
• Reviewer responsibilities
• PR templates
• Merge criteria

Review Checklists

What to look for during code reviews:

• Functionality and code quality
• Security (OWASP-aligned)
• Input validation, error handling, logging
• Performance and SAST integration

Language Recipes

Language-specific review guidance:

• TypeScript/JavaScript
• Python
• C#
• Go

Quick Start

For Authors

1. Keep PRs small and focused
2. Write clear descriptions
3. Self-review before requesting review
4. Respond to feedback constructively

For Reviewers

1. Review promptly (within 24 hours)
2. Be specific and constructive
3. Approve when good enough (not perfect)
4. Ask questions instead of making demands

Review Workflow

Metrics

Key Metrics to Track

What NOT to Measure

• Lines reviewed per hour (encourages rushing)
• Defects found (encourages nitpicking)
• Rejection rate (discourages thorough review)

Common Anti-Patterns

Rubber Stamping

Problem: Approving without actually reviewing Fix: Require substantive comments or explicit "reviewed, no issues found"

Nitpicking

Problem: Focusing on style over substance Fix: Use automated linting; focus on meaningful issues

Large PRs

Problem: 1000+ line PRs that can't be reviewed effectively Fix: Enforce PR size limits; break work into smaller chunks

Slow Reviews

Problem: PRs sitting for days without review Fix: Set SLAs; include review time in planning

Adversarial Tone

Problem: Comments that feel like attacks Fix: Training on constructive feedback; lead by example

Code Review in Regulated Environments

For FDA, HIPAA, FedRAMP compliance:

Documentation Requirements

• PR linked to work item/requirement
• Review comments preserved
• Approval recorded with identity
• Timestamp of review captured

Additional Review Criteria

• Security implications considered
• Audit trail maintained
• Compliance requirements verified
• Risk assessment updated if needed

Tools

PR Templates

Use templates to ensure consistent information:

• Description of changes
• Testing performed
• Screenshots (for UI changes)
• Checklist items

Automation

Automate what you can:

• Linting and formatting
• Test execution
• Security scanning
• Documentation generation

Review Tools

• GitHub PR reviews
• Azure DevOps pull requests
• GitLab merge requests
• Reviewable
• CodeStream

Best Practices Summary

Authors Should

• Self-review before requesting review
• Keep PRs focused and small
• Provide context in descriptions
• Respond promptly to feedback

Reviewers Should

• Review within 24 hours
• Be specific and constructive
• Approve when requirements are met
• Follow up on comments

Teams Should

• Set clear expectations (DoD, review criteria)
• Track and improve review metrics
• Automate style and format checks
• Foster psychological safety

Related Resources

• Team Agreements
• Automated Testing
• Microsoft Playbook: Code Reviews
• Google's Engineering Practices: How to do a code review
• OWASP Code Review Guide
• OWASP Cheat Sheet Series

---

Compliance

This section fulfills ISO 13485 requirements for software validation (4.1.5), control of records (4.2.4), design review (7.3.5), design verification (7.3.6), and monitoring and measurement (8.2.4), and ISO 27001 requirements for secure development lifecycle (A.8.25), application security requirements (A.8.26), secure coding (A.8.28), security testing (A.8.29), and information security in project management (A.5.8).

View full compliance matrix