[JSDoc] Practical commenting out with JSDoc

If we write code with proper naming and good readability, we might argue that comments are unnecessary because the code itself explains everything.

However, there are times when we need to explain aspects of the code that are external to the project. Additionally, there may be similar functions that have slightly different functionalities (although it's better to avoid such situations).

For example, let's consider the case where I need to work on the frontend for a program used in internet cafes (PC rooms).

But the backend is providing data in the following format:

[
  {
    id: 1,
    name: '10-hour pass',
    count: 10,
    price: 10000,
  },
  {
    id: 2,
    name: '20-hour pass',
    count: 20,
    price: 15000,
  },
];

However, the PC room wants to offer an event where they provide an additional 5000 won when users top up their balance by 3000 won. So, they want the data to be like this:

[
  {
    id: 1,
    type: 'time',
    name: '10-hour pass',
    count: 10,
    price: 10000,
  },
  {
    id: 2,
    type: 'time',
    name: '20-hour pass',
    count: 20,
    price: 15000,
  },
  {
    id: 3,
    type: 'money',
    name: 'Prepaid Top-up Event',
    count: 5000,
    price: 3000,
  },
];

The API will provide the data in this format, where the type indicates whether it's a time-based or money-based charge. If the type is "time," the count represents the number of hours to be charged. If the type is "money," the count represents the amount to be charged.

Although this is not an ideal structure, there might be situations where we have to work with it due to time constraints.

In this case, the charging method will vary depending on the type.

 

function charge(user, product) {
  if (product.type === 'time') {
    user.leftTime += product.count;
  } else if (product.type === 'money') {
    user.balance += product.count;
  }
  return user;
}

However, just by looking at the code, it's difficult to understand the role of count. Moreover, it's not clear whether the charge() function handles both time-based and money-based charging automatically when called.

To provide more guidance, we can add comments like this:

/**
 * Charge the user's remaining time or balance.
 * @param {User} user - The user object to be charged.
 * @param {String} type - The type of the charge: 'time' for time-based, 'money' for money-based.
 * @param {Number} count - The amount of time or money to be charged. For type 'time', it represents hours; for type 'money', it represents the amount.
 * @returns {User} - The user object with the updated balance or time.
 */
function charge(user, type, count) {
  if (type === 'time') {
    user.leftTime += count;
  } else if (type === 'money') {
    user.balance += count;
  }
  return user;
}

By providing this information and type hints when calling the function, we can ensure clarity and accuracy.

Let me introduce a few useful tips:

Bullet Points
You can use dashes or asterisks to create bullet points in your comments:

/**
 * Function for charging the user's remaining time or balance.
 * - Depth1
 *    - Depth2
 */

@type
You can specify the type of variables or parameters using the @type tag:

function charge(user, product) {
  /** @type {('time'|'money')} */
  const productType = product.type;
  /** @type {Number} */
  const productCount = product.count;
  if (productType === 'time') {
    user.leftTime = user.leftTime + productCount;
  } else if (productType === 'money') {
    user.balance = user.balance + productCount;
  }
  return user;
}

When you hover over productType, you will see the specified type.

@deprecated
The @deprecated tag can be used to indicate that a function or object should no longer be used:

/**
 * @deprecated Please do not use this anymore.
 */
function charge(user, product) {
  // ...
}

When this deprecated function or object is called, it will be displayed with a strikethrough style.

Other Tags
There are many other useful tags available in JSDoc, such as @version, @see, @async, and @this. I recommend exploring them and utilizing them in your documentation.

For more information and a comprehensive list of available tags, you can refer to the JSDoc documentation: https://jsdoc.app/