JavaScript Comments — Best Practices, JSDoc, and Clean Code in 2026

// Single-line comment — for brief inline notes
 
/*
  Multi-line comment — for longer explanations,
  block-level documentation, or temporarily disabling code
*/

/**
 * Calculates the total price after applying a percentage discount.
 *
 * @param {number} price    - Original price in USD (must be positive)
 * @param {number} discount - Discount percentage (0–100)
 * @returns {number} Discounted price rounded to 2 decimal places
 * @throws {RangeError} If discount is not between 0 and 100
 *
 * @example
 * applyDiscount(100, 20)  // returns 80.00
 * applyDiscount(49.99, 5) // returns 47.49
 */
function applyDiscount(price, discount) {
  if (discount < 0 || discount > 100) {
    throw new RangeError(`Discount must be between 0 and 100, got ${discount}`)
  }
  return parseFloat((price * (1 - discount / 100)).toFixed(2))
}

/**
 * @module AuthService
 * @description Handles user authentication, token management, and session
 * persistence. Uses JWT for stateless auth and bcrypt for password hashing.
 *
 * Security note: refresh tokens are stored in httpOnly cookies only.
 * Never expose them via JavaScript-accessible storage.
 */
 
class AuthService {
  /**
   * @param {import('./db').Database} db - Injected database connection
   * @param {string} jwtSecret           - Secret for signing JWT tokens
   */
  constructor(db, jwtSecret) {
    this.db = db
    this.jwtSecret = jwtSecret
  }
 
  /**
   * Authenticates a user and returns a signed JWT.
   *
   * @param {string} email    - User email address
   * @param {string} password - Plaintext password (hashed internally)
   * @returns {Promise<string>} Signed JWT valid for 1 hour
   * @throws {AuthError} If credentials are invalid
   */
  async login(email, password) {
    const user = await this.db.users.findByEmail(email)
    if (!user || !await bcrypt.compare(password, user.passwordHash)) {
      throw new AuthError('Invalid credentials')
    }
    return jwt.sign({ sub: user.id, email }, this.jwtSecret, { expiresIn: '1h' })
  }
}

// ❌ Redundant — the code already says this
i++ // increment i by 1
 
// ✅ Explains intent that isn't obvious from the code
const RETRY_LIMIT = 3   // API rate-limits after 3 rapid retries per second
 
// ❌ Redundant
const total = price * quantity   // multiply price by quantity
 
// ✅ Explains a non-obvious business rule
const total = price * quantity * 1.08   // 8% sales tax required in CA by AB-147

// ❌ Needs a comment because the code is unclear
// Check if the user is an admin who hasn't been banned
if (u.r === 1 && u.s !== 2) { ... }
 
// ✅ Self-documenting — no comment needed
const isActiveAdmin = user.role === 'admin' && user.status !== 'banned'
if (isActiveAdmin) { ... }

// TODO(sanjeevsharma): Replace with native Temporal API once Node 22 LTS ships
const formatDate = (d) => new Date(d).toLocaleDateString()
 
// FIXME: Race condition when two requests arrive within the same tick
// See issue #482 — requires mutex or queue-based approach
async function processPayment(orderId) { ... }
 
// HACK: The upstream API returns dates in M/D/YY format — normalise before parsing
const normalised = rawDate.replace(/(\d+)\/(\d+)\/(\d+)/, '20$3-$1-$2')
 
// NOTE: This intentionally returns null instead of throwing — callers must check
function findUser(id) { return users.find(u => u.id === id) ?? null }

// Debugging comment — temporary, remove before merging
console.log('[DEBUG] payload:', JSON.stringify(payload, null, 2))
 
// Documentation comment — permanent, meaningful to future readers
// We clone the array here to prevent the sort from mutating the original
// data prop, which would cause unexpected re-renders in the parent component
const sorted = [...items].sort((a, b) => a.name.localeCompare(b.name))

/**
 * Retries an async operation with exponential back-off.
 * Useful for transient network failures and rate-limited APIs.
 *
 * @param fn      - The async operation to retry
 * @param retries - Maximum number of attempts (default: 3)
 * @param delay   - Base delay in ms, doubled each attempt (default: 300)
 */
async function withRetry<T>(
  fn: () => Promise<T>,
  retries = 3,
  delay = 300
): Promise<T> {
  try {
    return await fn()
  } catch (err) {
    if (retries === 0) throw err
    // Exponential back-off: 300ms, 600ms, 1200ms
    await new Promise(res => setTimeout(res, delay))
    return withRetry(fn, retries - 1, delay * 2)
  }
}