The Craft of Readable Code

Code is read far more often than it is written. A function you author today might be read twenty times before it is changed — by teammates, by future you, by reviewers during a late-night incident. The return on clarity compounds silently over the life of a project.

What Makes Code Readable?

Readability isn’t style. It isn’t tabs versus spaces, or whether you prefer const over let. It’s about conveying intent to the next reader as efficiently as possible.

Three properties matter most:

1. Names that tell the truth. A variable named data tells you nothing. A variable named pendingInvoices tells you everything.
2. Functions that do one thing. When a function does two things and its name reflects only one of them, the second thing becomes invisible.
3. Structure that matches the mental model. If the reader has to mentally reorder your code to understand it, you’ve added accidental complexity.

The Newspaper Test

Try reading your code top-to-bottom as if it were a news article. The headline (function name) should give a summary. The opening sentences (early lines of the function) should establish context. Details should follow, not lead.

If you find yourself hunting for the “main point” of a function, that’s a signal.

Naming Things

The old joke that naming is one of the two hard problems in computer science is funny because it’s true. Here’s a pattern that helps:

• Use nouns for data: user, orderTotal, retryCount
• Use verbs for functions: fetchUser, computeTotal, incrementRetry
• Use questions for booleans: isLoading, hasError, canSubmit

// Before
function process(u: User, d: Date): boolean {
  const r = u.lastLogin < d;
  return r && u.active;
}

// After
function isEligibleForReactivation(user: User, cutoffDate: Date): boolean {
  const hasBeenInactive = user.lastLogin < cutoffDate;
  return hasBeenInactive && user.active;
}

The second version reads like a sentence. You can almost say it out loud.

Comments That Add Value

A comment that restates the code adds noise, not signal:

// Increment the counter
count++;

A comment that explains why something is done — that’s worth writing:

// Offset by 1 because the API uses 1-based indexing
const pageIndex = currentPage + 1;

The difference: the first comment could be deleted and nothing is lost. The second encodes context that cannot be recovered from the code alone.

Limiting Scope

Every variable and function should be as close to its use as possible. When a variable is declared fifty lines above where it’s used, the reader has to hold it in memory the entire time. That’s cognitive rent you’re charging them.

// Far declaration — creates mental overhead
let result: string;
// ... 40 lines of other code ...
result = formatName(user.firstName, user.lastName);
return result;

// Close declaration — pays as it goes
const formattedName = formatName(user.firstName, user.lastName);
return formattedName;

Running a Readability Review

Before opening a PR, try this:

• Read each function name aloud. Does it match what the function does?
• Find the longest function. Can it be split?
• Look for any comment that says what instead of why. Delete it.
• Ask: if you came back to this in three months with no context, what would confuse you?

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” — Martin Fowler

Readable code isn’t a luxury. It’s the difference between a codebase you can confidently change and one you fear touching.