Clean Code

Naming: Intention-Revealing Names

Names are the most important documentation in your code. A good name eliminates the need for a comment.

const d = new Date();
const u = getU();
const calc = (a, b) => a * b - (a * b * 0.1);

function proc(lst) {
  const res = [];
  for (const el of lst) {
    if (el.st === 'A') res.push(el);
  }
  return res;
}

const currentDate = new Date();
const currentUser = getCurrentUser();
const applyDiscount = (price, quantity) => {
  const subtotal = price * quantity;
  const discount = subtotal * DISCOUNT_RATE;
  return subtotal - discount;
};

function filterActiveUsers(users) {
  return users.filter(user => user.status === 'ACTIVE');
}

Naming Rules

Functions: Small and Focused

A function should do one thing, do it well, and do it only. If you cannot describe what a function does without using "and," it does too much.

• 📏 Size: 5-15 lines. If it scrolls, split it.
• 🎯 One thing: Extract helper functions aggressively.
• 3️⃣ Max 3 parameters. More than 3? Use an options object.
• 🚫 No side effects. A function named checkPassword should not also initialize a session.

function processOrder(user, items, address, coupon, notify) {
  // validate items (20 lines)
  // calculate totals (15 lines)
  // apply coupon (10 lines)
  // save to database (8 lines)
  // send notification (12 lines)
  // ... 65 lines total
}

function processOrder(order) {
  validateItems(order.items);
  const total = calculateTotal(order.items, order.coupon);
  const savedOrder = saveOrder(order.userId, order.items, total);
  notifyUser(order.userId, savedOrder);
  return savedOrder;
}

Comments: Why, Not What

If your code needs a comment to explain what it does, the code is not clear enough. Rewrite it. Comments should explain why — the intent, the reasoning, the trade-off.

// Increment counter by 1
counter++;

// Check if user is active
if (user.isActive) { ... }

// TODO: fix this later
// HACK: this works somehow
const result = data.map(x => x.value * 1.08);

// Tax rate is 8% per state regulation SB-1234,
// effective Jan 2025. See: legal/tax-policy.md
const TAX_RATE = 0.08;

// We retry 3 times because the payment gateway
// occasionally returns 503 during peak hours
const MAX_RETRIES = 3;

DRY: Don't Repeat Yourself

Every piece of knowledge should have a single, unambiguous representation. Duplication means bugs are fixed in one place but not the other.

The Rule of Three

Duplicate once? Tolerable. Duplicate twice (three instances)? Extract.

YAGNI: You Aren't Gonna Need It

Do not build features, abstractions, or infrastructure you do not need right now. Speculative code has a cost: it must be maintained, tested, understood, and eventually deleted when the predicted future never arrives.

• ❌ "Let's add a plugin system in case we need it later"
• ❌ "I'll build a generic framework for this one use case"
• ✅ Build the simplest thing that works. Refactor when a real need appears.

Error Handling: Fail Fast

Errors should be detected early, reported clearly, and never swallowed. Silent failures are the hardest bugs to diagnose.

try {
  const data = fetchData();
  processData(data);
} catch (error) {
  // ignore
}

// Or worse — returning null on error
function getUser(id) {
  try { return db.find(id); }
  catch { return null; }  // caller has no idea it failed
}

function getUser(id) {
  if (!id) throw new ValidationError('User ID is required');

  const user = db.find(id);
  if (!user) throw new NotFoundError(`User ${id} not found`);

  return user;
}

// Call site handles errors explicitly
try {
  const user = getUser(userId);
  renderProfile(user);
} catch (error) {
  if (error instanceof NotFoundError) {
    renderNotFound();
  } else {
    logger.error('Unexpected error fetching user', { error, userId });
    renderError();
  }
}

The Boy Scout Rule

• 📌 Rename an unclear variable you had to puzzle over
• 📌 Delete a commented-out block that has been there for months
• 📌 Add a type annotation to an any you now understand
• 📌 Extract a repeated magic number into a named constant

Clean Code Checklist