Code Quality and Readability

After this lesson, you will be able to: Write code that reads well to humans: name things accurately, comment only when needed, and use formatting + structure to communicate intent.

Code is read far more than it is written. Every line you write will be read by your future self, your teammates, and possibly someone who joins the team in two years. Optimize for them.

Prerequisites:Software Engineering vs Programming

Naming is the highest-leverage skill

A well-named variable is documentation that never goes stale. Bad: `let d = new Date(); let x = users.filter(u => u.a);`. Good: `const now = new Date(); const activeUsers = users.filter(user => user.isActive);`. Names should answer: what does this thing represent, in what units, in what state. Avoid abbreviations except for ubiquitous ones (id, url, db). Avoid Hungarian notation (`strName`, `iCount`); type systems do that job now.

When to comment, when not to

Comments are for the WHY, never the WHAT. Don't write: `// increment i by 1` next to `i++`. The code already says that. Do write: `// Skip retry on 4xx because the request itself is malformed` next to a conditional that looks weird out of context. If you find yourself writing many WHAT comments, the names are wrong. Rename first; comment last.

Self-documenting code, in practice

Compare these two versions of the same logic.

tsx

// Comment-heavy version
// Get the orders for this user
const o = await db.q(`SELECT * FROM orders WHERE u = ${userId}`);
// Filter to last 30 days
const recent = o.filter(x => x.d > Date.now() - 30 * 24 * 60 * 60 * 1000);
// Sum the totals
let s = 0;
for (const x of recent) s += x.t;

// Self-documenting version (no comments needed)
const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
const userOrders = await db.query(
  "SELECT id, total, created_at FROM orders WHERE user_id = $1",
  [userId],
);
const recentOrders = userOrders.filter(
  order => order.created_at.getTime() > Date.now() - THIRTY_DAYS_MS,
);
const totalSpent = recentOrders.reduce((sum, order) => sum + order.total, 0);

Function length and shape

A function should fit on a screen (about 30 lines). If it doesn't, the function is doing too many things. Functions should have one return type. A function that sometimes returns a number, sometimes a string, sometimes throws, is hard to use safely. Limit parameter count to about 3. More than that and callers can't remember the order; consider an options object.

Format on save, lint on commit

Use Prettier (or your language's equivalent) and let it own all formatting decisions. Use ESLint (or equivalent) to catch the unsafe patterns your team has agreed on. Hook both into Git pre-commit so they run before anyone reviews the code. Time arguing about tabs vs spaces is time not spent on the actual product.

Common mistakes only experienced engineers catch

Clever code that needs a paragraph to explain itself. If it can't be read, it can't be maintained. Names that lie. `getActiveUsers()` returns inactive ones too because someone added a flag and didn't rename. Rename or split. Wall-of-comments. Every line annotated. Usually a sign the code is doing too much; refactor instead of annotating. TODOs that linger for years. Track them as Jira tickets, not as code rot. Code that uses every language feature it can. Idiomatic > clever.

Quick Check

When is a comment most valuable?

Pick the cleanest answer.

←Reading Unfamiliar Code and Project Structure

Back to Engineering Fundamentals

Debugging Systematically→