Code readability is the clarity that lets developers understand and maintain a change. Code reviews encourage developers to present human-friendly code, improving maintainability and reducing future debugging effort. section 1.3.1
Treat readability as a shared team concern rather than a fixed personal preference. Human reviewers can interpret context and nuance, while each team decides what stability and maintainability require. section 3.1.2
During review, improve readability by:
- Comparing competing approaches with established conventions, best practices, patterns, and project style guides. section 6.1.1
- Adding explanatory comments or documentation when a reviewer cannot follow the code. section 6.1.1
- Checking complexity, consistency, code smells, tests, edge cases, and the relationship between an isolated change and the wider codebase. section 3.1.2
- Explaining the reasoning and goals behind each solution before seeking a clearer shared approach. section 6.1.1
Finding readable middle ground
If one implementation has clearer variable naming and another structures the logic more effectively, combine their strengths, pair-program a new solution, or involve another teammate. Choose the result that future developers can understand and maintain—not simply the version judged best by one person. section 6.1.1
Figure 6.4 The 5P process for suggesting a change during a code review
Use the 5P process for suggesting a change during a code review when readability feedback needs a structured, collaborative discussion. section 6.1.1
