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.

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

PR Comment

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

Emilie Chocolatecommented on Apr 2, 2025

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. Here’s how we can improve it:

proccessUser.ts

/**
 * 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
}