JSDocs

Where to write JSDocs

The JSDocs are required for all classes, methods, enums and global constants. Except for controller classes and methods.

Why to write JSDocs

The JSDocs are meant to help others to understand how code written by you can be used. They also will be useful for you if you ever need to read your code after couple of months, which happen often since most likely you will be asked to make some changes to your code, because you know it better.

Let us imagine a situation where a coder named John have written a function sumNumbers(num1: number, num2: number), which as name suggests sum up the two numbers together.

At some point, you have to use the sumNumbers() function in your code. After you put the function to your code an error is thrown to the terminal. You find the place of the error, it is that sumNumbers() function, you hover a cursor to the function in your IDE hoping to find some explanation what could be wrong. But there are no JSDocs written for that function and you have no idea why the error occurred. Here you have two options:

1. You can write a message to John and asking him why this happen. If you are lucky, you get an answer quickly in 5 min, but what if it takes a day?
2. You can go and read the code for couple of minutes and find out why the error occurred.

Most likely you will choose the second variant and spend 2 minutes to find out that the function is throwing the error, because one of the numbers is negative (for any reason known only by John). You change your code to not put negative numbers to the sumNumbers() function and move on.

This example rises a question why John did not write about this behavior. If we measure how fast a JSDoc comment can be written, it is gonna be 2-5 minutes. This is not much time especially if the function is used by couple of developers. Assuming that reading the function code take 2 minutes, that means that the JSDoc can save 2*2=4 min of time for the whole team.

This is why the JSDocs are required.

What to write in JSDocs

The content of the JSDocs can be different. The main idea that it should answer the questions how to use the code and what are the possible side effects.

In the example with John and his sumNumbers() function the JSDoc could be as follow:

/**
 * Sums two numbers and returns the result.
 *
 * @param num1 The first number to sum. Must be a non-negative number.
 * @param num2 The second number to sum. Must be a non-negative number.
 * @returns The sum of provided numbers.
 *
 * @throws Throws an error if either of the provided numbers is negative.
 *
 * @example ```ts
 * const sum = sumNumbers(5, 10); // 15
 * ```
 *
 * @example ```ts
 * // Throws an error:
 * sumNumbers(-5, 10);
 * ```
 */
function sumNumbers(num1: number, num2: number){
    if(num1 < 0 || num2 < 0)
        throw new Error();
    
    return num1 + num2;
}

When to write the JSDocs

JSDocs can written whenever you want, but before making pull request.

You can write the JSDocs before the function implementation in order to "explain" yourself and think how the function should work first and then start its implementation.

Writing JSDocs after the whole code is written is also a valid moment.