Code Reviews: An Incomplete Guide

Code Reviews: An Incomplete Guide

Note: This is a republication on Substack of the original 2019 post.

Chancellor explores code reviews as fundamental to software engineering teamwork. He argues that as projects grow in complexity, individual programmers must evolve into collaborative engineers, with code reviews serving as the essential unit of collaborative work.

Goals of Code Review

Code reviews function as collaborative editing opportunities, similar to an editor preparing a manuscript for publication. Rather than acting as gatekeepers preventing “bad code,” reviewers should approach the process constructively. Chancellor emphasizes that experience level doesn’t determine review value: “if you don’t understand what is being done in a pull request, probably other people won’t either: ask questions!”

Initiating Pull Requests

Before coding, engineers should discuss proposed changes with teammates. Work-in-progress pull requests help when difficulties arise. Upon completion, developers should squash commits and write comprehensive commit messages explaining the “why” rather than merely restating code changes.

Commit Message Structure

Effective commit messages include:

• Previous code behavior
• Reason for changes
• New behavior outcome
• Associated tickets/issues

Messages should be under 80 characters for the summary line and include dedicated Summary and Test Plan sections.

Code Review Conduct

Reviewers must recognize that submitting code represents vulnerability. Constructive feedback requires clear communication acknowledging that no engineer produces perfect code initially. Reviewees should separate personal identity from their code contributions.

Merging Process

In pull request workflows, repository owners typically merge approved code, signifying shared responsibility for the changes entering the main branch.

Why Code Reviews Matter

The essay emphasizes that code reviews serve multiple essential functions:

1. Quality Assurance: Multiple perspectives catch bugs and design issues
2. Knowledge Sharing: Team members learn from each other’s approaches
3. Code Consistency: Ensures codebase maintains coherent style and patterns
4. Documentation: Review discussions provide context for future maintainers
5. Team Building: Collaborative improvement builds trust and shared ownership

Cultural Aspects

Chancellor notes that effective code review requires deliberate cultural cultivation:

• Psychological Safety: Team members must feel safe submitting imperfect code
• Constructive Criticism: Feedback focuses on improvement, not judgment
• Mutual Respect: All team members’ perspectives receive consideration
• Continuous Learning: Reviews as learning opportunities for everyone involved
• Shared Ownership: The team collectively owns the codebase

Common Pitfalls

The essay identifies several common code review failures:

• Rubber Stamping: Approving without genuine review to avoid conflict
• Nitpicking: Focusing on trivial style issues while missing substantial problems
• Ego Defense: Reviewees taking criticism personally rather than professionally
• Power Dynamics: Senior engineers dismissing junior perspectives inappropriately
• Poor Communication: Vague or harsh feedback that doesn’t guide improvement

Best Practices Summary

Chancellor summarizes key practices for effective code reviews:

For Reviewees: - Discuss changes before implementing - Break large changes into reviewable chunks - Write clear commit messages - Respond professionally to feedback - Ask clarifying questions

For Reviewers: - Approach reviews as collaborative editing - Provide specific, actionable feedback - Acknowledge good practices observed - Ask questions to understand intent - Suggest alternatives with reasoning

For Teams: - Establish clear review expectations - Allocate time for thorough reviews - Cultivate psychological safety - Document common patterns - Continuously improve the process

Conclusion

The essay concludes that mastering code reviews represents a crucial transition from individual programming to team software engineering. As projects grow in complexity beyond what individuals can comprehend, effective collaboration through code reviews becomes the primary mechanism for maintaining quality and shared understanding.

Teams that invest in developing strong code review practices build better software, grow stronger engineers, and create more resilient organizations.

Read and subscribe on Substack