Code Readability

Let’s look at how to improve code readability in code reviews. We’ll show you a simple example and explain why the feedback matters.

The Scenario

A developer has written code to check if a user is eligible to drive. The code works but could be more readable.

drivingEligibility.ts


// Before
function canDrive(user) {
  return (
    user.age >= 16 &&
    user.hasLicense &&
    !user.isSuspended &&
    user.visionTestPassed &&
    user.medicalCheckPassed
  )
}

How will you comment on this code?

Choose the option that you think is the most constructive and helpful.

Itsik Mamancommented on Apr 2, 2025

This condition is hard to read. Break it into multiple lines.

Itsik Mamancommented on Apr 2, 2025

Consider breaking down the condition into smaller parts and using descriptive variable names for better readability.

Itsik Mamancommented on Apr 2, 2025

Thanks for implementing the driving eligibility check! Breaking down the condition into descriptive variables makes the code’s intent much clearer. This helps other developers understand the business logic more easily. Here’s how we can improve it:

drivingEligibility.ts


// After
function canDrive(user) {
  const meetsAgeRequirement = user.age >= 16;
  const hasValidLicense = user.hasLicense && !user.isSuspended;
  const passedRequiredTests = user.visionTestPassed && user.medicalCheckPassed;
 
  return meetsAgeRequirement && hasValidLicense && passedRequiredTests;
}

Understanding the Improvements

Click here to learn more

1. Code Clarity

Original code has a long, complex condition
New code uses descriptive variable names
Clear explanation of each requirement

2. Maintainability

Easier to understand and modify
Easier to debug issues
Easier for new team members to learn

3. Documentation

Code is self-documenting
No need for additional comments
Clear for other developers

Tips for Improving Code Readability

Start with Something Positive
- Acknowledge the working code
- Show you understand the current approach
- Example: “Great work on the driving eligibility check!”
Explain the Benefits
- Why does readability matter?
- How does it help the team?
- Example: “This makes the code’s intent clearer”
Be Specific
- Suggest concrete improvements
- Explain why they matter
- Example: “Using descriptive variables helps other developers understand the logic”
Keep It Friendly
- Focus on improvement, not criticism
- Use encouraging language
- Example: “Thanks for considering code readability!”

Common Pitfalls to Avoid

Being Too Critical
- ❌ “This code is unreadable. Fix it.”
- ✅ “Good work! Here’s how we can make the code even clearer.”
Not Explaining Why
- ❌ “Break this into smaller parts.”
- ✅ “Breaking down the condition into descriptive variables helps other developers understand the business logic.”
Ignoring the Positive
- ❌ “This needs better readability.”
- ✅ “Great work! Here’s how we can make it even more readable.”

Remember: The goal is to help your teammate write better code while maintaining a positive and collaborative environment!

Last updated on April 11, 2025