JavaScript Comments – Writing Clean, Documented Code

// This is a standalone comment explaining the next line
const TAX_RATE = 0.08;   // 8% sales tax — required by state law

// Calculate the final price including tax
function addTax(price) {
  return price * (1 + TAX_RATE);
}

// Single-line comments are ideal for:
// - Brief explanations
// - Annotating specific values or magic numbers
// - Quick notes during development

/*
  This function validates a UK postcode format.
  Valid examples: "SW1A 1AA", "EC2R 8AH", "W1A 0AX"

  Note: This is a simplified regex — it does NOT guarantee
  the postcode actually exists in Royal Mail's database.
  Use a postcode lookup API for verified addresses.
*/
function isValidUKPostcode(postcode) {
  const regex = /^[A-Z]{1,2}[0-9][A-Z0-9]? ?[0-9][A-Z]{2}$/i;
  return regex.test(postcode.trim());
}

/* Quick inline multi-line comment */
const MAX = /* the theoretical max before overflow */ 2147483647;

function processOrder(order) {
  // validateOrder(order);   // Temporarily disabled while debugging
  const total = calculateTotal(order.items);

  /*
  // Old discount logic — keeping for reference
  if (order.coupon) {
    total = total * 0.9;
  }
  */

  // New discount logic
  if (order.coupon && isValidCoupon(order.coupon)) {
    return total * getCouponDiscount(order.coupon);
  }

  return total;
}

/**
 * Calculates the area of a rectangle.
 *
 * @param {number} width - The width of the rectangle in pixels.
 * @param {number} height - The height of the rectangle in pixels.
 * @returns {number} The area in square pixels.
 * @throws {Error} If width or height is negative.
 *
 * @example
 * const area = rectangleArea(10, 5);
 * console.log(area); // 50
 */
function rectangleArea(width, height) {
  if (width < 0 || height < 0) {
    throw new Error("Width and height must be non-negative.");
  }
  return width * height;
}

/**
 * Represents a user in the system.
 * @typedef {Object} User
 * @property {string} id - Unique user identifier.
 * @property {string} name - Display name.
 * @property {string} email - Email address.
 * @property {boolean} isAdmin - Whether the user has admin privileges.
 */

/**
 * Fetches a user by their ID.
 * @param {string} userId - The user's unique identifier.
 * @returns {Promise<User|null>} The user object, or null if not found.
 */
async function getUserById(userId) {
  // implementation...
}

// ❌ BAD COMMENTS — These explain WHAT the code does (already obvious)
// Declare a variable called count and set it to 0
let count = 0;

// Add 1 to count
count++;

// Return the user's name
return user.name;

// ✅ GOOD COMMENTS — These explain WHY (not obvious from code)
// Start counting from 0; the display will add 1 for 1-based numbering
let count = 0;

// Increment on each failed attempt; lockout triggers at MAX_ATTEMPTS
count++;

// Return the display name — falls back to email prefix if name isn't set
return user.name || user.email.split("@")[0];

// ✅ GOOD: Explain a non-obvious business rule
// Per GDPR Article 17, we must not log the user's IP address
const requestLog = { timestamp, endpoint };  // IP deliberately excluded

// ✅ GOOD: Explain a workaround
// Array.from() instead of spread operator due to IE11 transpilation bug (see #GH-412)
const items = Array.from(nodeList);

// TODO: Add input validation before this goes to production
function saveUser(data) {
  db.insert(data);
}

// FIXME: This breaks when the user list is empty — returns undefined
function getFirstUser(users) {
  return users[0].name;
}

// HACK: Temporary fix for the timezone offset bug — remove after Q3 backend update
const adjustedDate = new Date(timestamp - 3600000);

// NOTE: This algorithm is O(n²) — acceptable for now with small datasets,
//       but needs to be replaced with a hash map approach for scale
function findDuplicate(arr) {
  for (let i = 0; i < arr.length; i++) {
    for (let j = i + 1; j < arr.length; j++) {
      if (arr[i] === arr[j]) return arr[i];
    }
  }
}

// Disable a rule for one line (add explanation!)
const result = eval(expression); // eslint-disable-line no-eval -- sandboxed input, validated upstream

// Disable for the next line
// eslint-disable-next-line no-console
console.log("Debug output:", data);

// Disable for a block
/* eslint-disable no-magic-numbers */
const RETRIES = 3;
const TIMEOUT = 5000;
const MAX_SIZE = 1048576;
/* eslint-enable no-magic-numbers */

// Disable for the entire file (rarely justified — use at the top)
/* eslint-disable no-unused-vars */