Effective documentation and consistent formatting are key to making code readable and maintainable. This guide covers the usage of JSDoc and the dos and don’ts of commenting and formatting.

​
JSDoc for JavaScript

JSDoc is a popular tool for documenting JavaScript code. It helps in understanding the purpose of functions, parameters, and return types.

​
Good JSDoc Example

/**
 * Adds two numbers together.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The sum of the two numbers.
 */
function sum(a, b) {
  return a + b;
}

​
Bad JSDoc Example

// Adds a and b
function sum(a, b) {
  return a + b;
}
// Missing detailed JSDoc comment

​
Proper Use of Multi-Line Comments

Multi-line comments are useful for providing detailed explanations or summarizing blocks of code.

​
Good Multi-Line Commenting Practice

/**
 * This function calculates the total price of an order
 * including tax and discount. It applies a tax rate of 8%,
 * and a discount rate is applied if applicable.
 *
 * @param {number} basePrice - The base price of the order.
 * @param {boolean} hasDiscount - Indicates if the order has a discount.
 * @returns {number} The total price after applying tax and discount.
 */
function calculateTotalPrice(basePrice, hasDiscount) {
  const taxRate = 0.08;
  let discount = 0;
  if (hasDiscount) {
    discount = basePrice * 0.1; // 10% discount
  }
  return basePrice + (basePrice * taxRate) - discount;
}

​
Bad Multi-Line Commenting Practice

/*
  This function calculates the price.
  It has parameters.
  It returns a number.
*/
function calculateTotalPrice(basePrice, hasDiscount) {
  // The actual function code
}
// Non-informative, redundant comments

​
Including Meaningful Comments & Avoiding Redundancy

Strategic comments enhance code clarity, but beware of redundancy. Prioritize meaningful insights to facilitate collaboration and understanding among developers.

​
Good Practice

// Loop through users and apply discounts to eligible ones
users.forEach(user => {
  if (user.isEligibleForDiscount()) {
    applyDiscount(user);
  }
});

// Calculate the area of a rectangle
function calculateArea(length, width) {
  return length * width;
}

​
Bad Practice

// Start a loop
users.forEach(user => {
  // Check if the user is eligible for discount
  if (user.isEligibleForDiscount()) {
    // Apply discount to the user
    applyDiscount(user);
  }
});
// Redundant comments that simply restate the code

// Calculate area
function calculateArea(l, w) {
  return l * w;
  // Ambiguous and unhelpful comment
}

​
Indentation and Formatting

Consistent indentation and formatting are crucial for readability.

​
Good Practice

Use consistent indentation (e.g., 2 or 4 spaces) and follow a style guide.

function exampleFunction() {
  if (condition) {
    // code
  }
}

​
Bad Practice

Mixing tabs and spaces or inconsistent indentation.

function exampleFunction() {
if(condition){
// code
}
}
// Inconsistent indentation

​
Consistent Formatting

Adhering to a consistent code formatting style across your project is important.

​
Good Practice

Follow a formatting standard like Airbnb’s JavaScript Style Guide or Google’s JavaScript Style Guide.

​
Bad Practice

Inconsistent naming conventions, brace styles, or line breaks.

Remember, the goal of these practices is to make your code as clear and maintainable as possible. Well-documented and formatted code not only benefits you but also your fellow developers who may work on your code in the future.