Coding Standards

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

The Scenario

A developer has written code to handle user data. The code works but could follow better naming conventions and organization.

userData.ts


// Before
function p(u) {
  if (u.a > 18) {
    u.s = 'adult'
  } else {
    u.s = 'minor'
  }
  return u
}

PR Comment

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

Nora Lavendercommented on Apr 2, 2025

The variable names need to be more descriptive. This is hard to read.

Isabel Fuchsiacommented on Apr 2, 2025

Use better variable names.

Clovis Goldcommented on Apr 2, 2025

The function name ‘p’ should be more descriptive, like ‘processUser’. Also, variables ‘u’, ‘a’, and ‘s’ should be renamed to be clearer.

Melisandra Beigecommented on Apr 2, 2025

Thanks for implementing the user status logic! Using descriptive variable names makes the code more readable and helps other developers understand the code’s purpose. Here’s how we can improve it:

userData.ts


// After
function updateUserAgeStatus(user: User) {
  if (user.age > 18) {
    user.status = 'adult'
  } else {
    user.status = 'minor'
  }
  return user
}

Click here to learn more

Improvements

1. Code Clarity

The original code uses cryptic variable names
The new version clearly shows what the code does
Function name describes its purpose

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

1. Start Positive

Acknowledge the working code
Show you understand the current approach
Example: “Great work on the user status logic!“

2. Explain the Benefits

Why do these practices matter?
How do they help the team?
Example: “This makes the code more readable”

3. Be Specific

Suggest concrete improvements
Explain why they matter
Example: “Using descriptive variable names helps other developers”

4. Keep It Friendly

Focus on improvement, not criticism
Use encouraging language
Example: “Thanks for considering code quality!”

Common Pitfalls to Avoid

1. Being Too Critical

❌ “These variable names are terrible.”
✅ “Good work! Here’s how we can make the code even clearer.”

2. Not Explaining Why

❌ “Use better names.”
✅ “Using descriptive names helps other developers understand the code.”

3. Ignoring the Positive

❌ “This needs better naming.”
✅ “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

Code Readability Security Concerns