Best Practices in Code Documentation and Formatting

Learn the essentials of using JSDoc, and effective commenting, along with indentation and formatting best practices.

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.