Code Documentation

Let’s look at how to suggest improvements for code documentation 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 benefit from better documentation.

Less Helpful Approach

// Before
function processUser(userId: string) {
  const user = db.getUser(userId)
  return user
}

❌ Less Helpful:

Review Comment:

“Add comments.”

Why This Isn’t Helpful:

• Doesn’t explain what comments are needed
• Doesn’t suggest specific improvements
• Feels critical without being constructive
• Doesn’t explain the benefits of documentation

More Helpful Approach

// After
/**
 * Retrieves and processes user data from the database.
 *
 * @param userId - The unique identifier of the user to process
 * @returns The processed user data
 * @throws {UserNotFoundError} If the user is not found in the database
 */
function processUser(userId: string) {
  const user = db.getUser(userId)
  return user
}

✅ More Helpful:

Review Comment:

“Great work on the user processing! Adding JSDoc comments helps other developers understand the function’s purpose and requirements. This makes the code more maintainable and easier to use correctly.”

Why This Is Better:

1. Acknowledges the working code
2. Explains the benefits of documentation
3. it Points out specific improvements
4. Uses friendly, encouraging language

Understanding the Improvements

1. Code Clarity

• Clear function purpose
• Documented parameters
• Expected return values

2. Error Handling

• Documented error cases
• Clear error conditions
• Better error understanding

3. Maintainability

• Easier to understand
• Better code navigation
• Clearer usage examples

Tips for Suggesting Documentation Improvements

1. Start with Something Positive

   • Acknowledge the working code
   • Show you understand the current approach
   • Example: “Great work on the user processing!”

2. Explain the Benefits

   • Why does documentation matter?
   • How does it help?
   • Example: “This makes the code more maintainable”

3. Be Specific

   • Suggest concrete improvements
   • Explain why they matter
   • Example: “Adding JSDoc comments helps with code understanding”

4. Keep It Friendly

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

Common Pitfalls to Avoid

1. Being Too Critical

   • ❌ “This needs documentation.”
   • ✅ “Good work! Here’s how we can make it even more maintainable.”

2. Not Explaining Why

   • ❌ “Add comments.”
   • ✅ “Adding JSDoc comments helps other developers understand the code.”

3. Ignoring the Positive

   • ❌ “This needs better documentation.”
   • ✅ “Great work! Here’s how we can make it even more helpful.”

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