Kieran Barker

How to document your JavaScript functions

I use liberal comments in my JavaScript programs, but people often ask me specifically about the way I document my functions. So let's get right to it.

I use a style of documentation called JSDoc for all my JavaScript functions. It has a few benefits, such as:

  • Making code more explicit;
  • Being supported by modern text editors; and
  • Automatically generating a documentation website for a project.

I'm mainly interested in the first two. Let's look at a simple example. We have a function that returns a greeting with a person's name:

/**
 * Say hello to someone
 * @param {String} name The person's name
 * @returns {String} A greeting
 */
function sayHello (name) {
  return `Hello, ${name}!`;
}

The three lines in this comment block immediately make it clear:

  1. What the function does;
  2. What parameters it takes and what type they are; and
  3. What the return value is and what type it is.

And when I hover over the function name in VS Code, my editor surfaces that information:

A screenshot showing that VS Code surfaces JSDoc comments when the user hovers over a function name.
Hovering over the function name surfaces the documentation.

If you haven't already, give it a try. This style of commenting will give your programs an air of professionalism, and it's a great habit to get into. Writing good documentation is key to being a professional developer who works as part of a team.