JS Comments

JavaScript Comments: Single-Line, Multi-Line, & JSDoc

Comments explain JavaScript code, increase maintainability, enable IDE IntelliSense, and prevent execution during debugging. The JavaScript engine completely ignores comments during parsing and execution.

Comment Types Taxonomy

flowchart TD
    Comments["JavaScript Comments"] --> Single["Single-Line: // Comment"]
    Comments --> Multi["Multi-Line: /* ... */"]
    Comments --> JSDoc["JSDoc Annotations: /** ... */"]
    JSDoc --> TypeDoc["Provides Type Safety & Autocompletion in IDEs"]

Comment Formats Comparison

Practical Code Example

// ==========================================
// Single-Line Comment: Configuration Setup
// ==========================================
const API_TIMEOUT = 5000; // Timeout in milliseconds

/* 
 * Multi-Line Comment:
 * The following section handles caching policy calculation.
 * Ensures local storage is checked prior to making network calls.
 */

/**
 * Calculates total invoice price including tax and discount.
 * 
 * @param {number} basePrice - Base item price before adjustments.
 * @param {number} taxRate - Tax percentage expressed as decimal (e.g., 0.15 for 15%).
 * @param {number} [discount=0] - Optional discount amount to subtract.
 * @returns {number} Final calculated price rounded to two decimal places.
 */
function calculateInvoiceTotal(basePrice, taxRate, discount = 0) {
  if (basePrice <= 0) return 0;
  const taxableAmount = basePrice - discount;
  const total = taxableAmount + (taxableAmount * taxRate);
  return Number(total.toFixed(2));
}

// Example Execution
const finalPrice = calculateInvoiceTotal(100, 0.15, 10);
console.log(`Calculated Invoice Total: \$${finalPrice}`);

Best Practices & Gotchas

• Explain "Why", Not "What": Avoid repeating what the code already says (e.g., let x = 5; // assigns 5 to x). Comment on business logic decisions and non-obvious algorithms.
• Use JSDoc for Libraries: Annotating public functions with JSDoc grants VS Code and editor users instant hover documentation and type hints.
• Remove Dead Code Comments Before Deployment: Stale commented-out code degrades repository readability.

Self-Check Challenge

Write a JSDoc block for a function fetchUserData(userId) that accepts a numeric userId and returns a Promise resolving to an Object.