JSDoc vs. Regular Comments

JavaScript has something called "JSDoc comment". The idea of a JSDoc comment is pretty simple: If you use a multi-line comment right above a function, it serves as the documentation for that function. For example:

/**
 * Greets a user by their name.
 *
 * @param {string} name - The name of the user.
 * @returns {string} A greeting message.
 */
function hello(name) {
  return `Hello, ${name}!`;
}

The above function couldn't be simpler: It takes a parameter and then returns a friendly greeting with that parameter. The comment above the function acts as its documentation. It doesn't affect the function's execution, but it allows us to get help on the function.

Many modern code editors can display this documentation when you hover over the function or when you use a tool that generates documentation from comments.

Now, the first thing to consider is what a JSDoc comment should contain. Back when I was an undergraduate, my software engineering professor told us that the documentation for a function should indicate three things:

(1) What it expects/requires as inputs,

(2) what it modifies, and

(3) what it returns.

If you document all three of these for every function you write, you're way ahead of the game. Providing examples is just icing on the cake.

Many of my JavaScript students like the idea of JSDoc comments, but have a hard time understanding why JavaScript seems to have two comment syntaxes. It's thus important to stress that there is a world of difference between comments and JSDoc comments.

Comments are meant for the people who will be maintaining a program. They describe the implementation details and are there to guide and assist developers who will need to add features and fix bugs. You can think of comments as the instruction guide your mechanic has bought before working on your car: It's full of technical details for fixing every part.

However, just as you cannot learn to drive your car from the mechanic's guide, you can't use a function from reading the comments. It's the API documentation—the JSDoc comments, in the case of JavaScript—that describe the how and why of using the function.

In other words, JSDoc comments and comments are aimed at completely different audiences and should be written as such: Comments should be written so that someone can debug, maintain, and improve your function as quickly and easily as possible. JSDoc comments are aimed at a much larger audience and should thus make it easy for someone to understand what your function does, how to run it, and what it returns.

The code that you write should have both comments and JSDoc comments. But if you have to choose one over the other, I'd suggest JSDoc comments, as your functions are likely to have more users than maintainers.