Writing Code the Next Person Can Understand

Code is written once and read many times. Every bug investigation, every new feature and every review means someone reading code they did not write, or wrote so long ago it might as well be someone else's. Increasingly, that someone is an AI assistant, which reads very literally and takes clever shortcuts at face value.

Readable code is not a luxury. It is what makes a codebase safe to change. Here are the habits we follow.

Names that say what things are

A good name removes the need for a comment. A function called "process" tells the reader nothing; one called "refund platform fee for reversed sale" tells them nearly everything. We prefer names that are a little long and completely clear over names that are short and mysterious.

The same applies to variables, settings and database columns. A setting called "auto" could mean anything. A setting called "auto renew domains" means one thing.

Match the surrounding code

Every codebase has its own style: how it names things, how much it comments, how it structures similar code. New code should read like the code around it. A function that uses a different style from its neighbors makes readers wonder whether the difference means something.

We ask both people and assistants to match the surrounding style, including its comment density and idioms, rather than imposing a personal preference.

Comments explain why, not what

Code shows what it does. Comments are most valuable when they explain why: why a step is necessary, why an obvious approach was avoided, what would break if the line were removed. A comment like "increment the counter" adds noise. A comment like "jobs can run twice, so record fulfillment before granting access" prevents a future bug.

Some of our most important comments explain hard-won lessons, such as why certain styles must live in a specific cascade layer. Those comments protect the code from well-meaning changes that would reintroduce old problems.

Small, focused pieces

A function that does one thing is easier to name, test and understand than one that does six. When a function grows long or starts handling several unrelated concerns, we split it. Each piece then has a clear purpose and a clear name.

Prefer obvious over clever

Clever code is satisfying to write and costly to read. A compact trick that saves three lines but takes three minutes to understand is a bad trade. We prefer straightforward code that a reader understands on the first pass, even if it is slightly longer.

Make the safe path the easy path

Readable code also means designing helpers so the correct choice is the obvious one. A helper that returns only the current account's members makes it natural to build safe dropdowns. A single gate for sign-in decisions makes it natural to respect two-factor authentication. When the safe path is the easy path, readers and writers both make fewer mistakes.

Delete what is not used

Unused code is a tax on every reader, who must work out whether it matters. Our Zero Dead Code rule keeps the codebase free of functions and settings that nothing uses, so readers can trust that what exists is there for a reason.

Write for assistants too

AI assistants read code differently from people. They follow patterns closely, sometimes too closely, and they rely on names and comments to understand intent. Clear names, consistent patterns and explanatory comments help assistants make good changes. Confusing code tends to produce confused changes, whoever is making them.

Review for readability

Code review is where readability is enforced. Reviewers ask: would someone new understand this? Is the name honest? Does the comment explain the reason? If the reviewer struggles to follow it, the code changes before it merges.

Readable code also makes handoff notes shorter and reviews with AI assistants more reliable, because the code explains itself.

Frequently asked questions

Why is readable code important?

Code is read far more often than it is written. Readable code is faster to fix, safer to change and easier for new developers and AI assistants to work with.

Should code have lots of comments?

Comments should explain why something is done, especially non-obvious decisions. Clear names reduce the need for comments that only describe what the code does.

What makes a good function name?

A good name describes exactly what the function does, so a reader understands its purpose without reading its body.