How to Write Single and Multi-Line Comments in JavaScript

// This is a single-line comment
const name = "Alice";
 
// Calculate the discount based on membership level
const discount = calculateDiscount(membership);
 
const tax = 0.08; // Tax rate for the current region

// Position 1: Above the code (most common)
// Validate that the user has an active subscription before proceeding
if (user.subscription.status === "active") {
  grantAccess(user);
}
 
// Position 2: End of line (for brief clarifications)
const MAX_RETRIES = 3; // Matches the API gateway timeout policy
const TIMEOUT_MS = 5000; // 5 seconds

// This comment does not slow down your code
const x = 10; // Neither does this one
// Even a thousand comments have zero runtime cost
const y = 20;

/* This is a multi-line comment.
   It can span as many lines as needed.
   The engine ignores everything between the markers. */
const greeting = "Hello, World!";

/*
  Configuration object for the payment gateway.
  All values are loaded from environment variables at startup.
  See docs/payment-setup.md for the full configuration reference.
*/
const paymentConfig = {
  apiKey: process.env.PAYMENT_API_KEY,
  merchantId: process.env.MERCHANT_ID,
  environment: process.env.NODE_ENV === "production" ? "live" : "sandbox"
};

// Style 1: Stars aligned on the left (most common)
/*
 * Handle the checkout process.
 * Validates the cart, applies discounts,
 * and processes the payment.
 */
function processCheckout(cart) {
  // ...
}
 
// Style 2: No leading stars (simpler)
/*
  Handle the checkout process.
  Validates the cart, applies discounts,
  and processes the payment.
*/
function processCheckout(cart) {
  // ...
}

// Comment out one argument for testing
const result = calculate(width, /* height, */ depth);
 
// Temporarily change a value
const environment = /* "production" */ "development";

/* This outer comment starts here
   /* This inner comment seems fine */
   but this text is no longer commented and causes a syntax error
*/

/**
 * Calculate the total price including tax and discount.
 * @param {number} subtotal - The pre-tax, pre-discount amount
 * @param {number} taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @param {number} [discount=0] - Optional discount amount to subtract
 * @returns {number} The final price rounded to 2 decimal places
 */
function calculateTotal(subtotal, taxRate, discount = 0) {
  const taxAmount = subtotal * taxRate;
  const total = subtotal + taxAmount - discount;
  return Math.round(total * 100) / 100;
}

/**
 * Represents a user in the system.
 * @typedef {Object} User
 * @property {string} name - Display name
 * @property {string} email - Email address
 * @property {string} role - One of "admin", "editor", "viewer"
 * @property {Date} createdAt - Account creation timestamp
 */
 
/**
 * Find a user by their email address.
 * @param {string} email - The email to search for
 * @returns {User|null} The matching user, or null if not found
 */
function findUserByEmail(email) {
  return users.find(u => u.email === email) || null;
}

// Disable a single line
// console.log("Debug output:", data);
 
// Disable multiple lines
/*
validateUser(user);
sendNotification(user);
logActivity(user);
*/
 
// Disable part of an expression
const features = {
  darkMode: true,
  // notifications: true,  // Disabled until backend is ready
  analytics: false
};

// TODO: Implement pagination for the user list
function getUsers() {
  return fetchAllUsers(); // Returns everything for now
}
 
// FIXME: This breaks when the array is empty
function getAverage(numbers) {
  return numbers.reduce((a, b) => a + b) / numbers.length;
}
 
// HACK: Workaround for browser bug in Safari 17
element.style.transform = "translateZ(0)";
 
// NOTE: This timeout matches the server-side session duration
const SESSION_TIMEOUT = 30 * 60 * 1000;
 
// WARNING: Changing this value requires a database migration
const MAX_USERNAME_LENGTH = 50;
 
// @ts-ignore - Suppress TypeScript error on next line
// @ts-expect-error - Expected TypeScript error on next line

<!-- This is an HTML comment -->
<script>
  // This is a JavaScript comment inside a script tag
  const x = 10;
</script>

/* This is a CSS comment */
.container {
  width: 100%; /* Inline CSS comment */
}

// 1. File header: describe the module's purpose
/**
 * User authentication middleware.
 * Validates JWT tokens and attaches the user object to the request.
 * Requires AUTH_SECRET environment variable to be set.
 */
 
// 2. Before complex logic: explain WHY, not WHAT
// Use binary search instead of linear scan because the roster
// is sorted and can contain up to 50,000 entries
const index = binarySearch(roster, targetId);
 
// 3. Before regex patterns: always explain regex
// Match email format: local@domain.tld (RFC 5322 simplified)
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
// 4. Before magic numbers: explain the value
const EARTH_RADIUS_KM = 6371; // Mean radius in kilometers (WGS 84)
 
// 5. Before workarounds: explain the constraint
// Safari does not support the `gap` property in flexbox below v14.1
// Using margin-based spacing as a fallback

// Bad: restates the code
// Set count to 0
let count = 0;
 
// Good: explains the reason
// Reset count when switching tabs to prevent stale data accumulation
let count = 0;

// Bad: needs comment
const d = 30; // days until expiration
 
// Good: self-documenting
const daysUntilExpiration = 30;