Code Readability

Code does two things: it runs, and it gets read. In the agent era both audiences matter — humans review intent and architecture, and agents synthesise the rest. Both need code that’s legible at a glance.

Two requirements

1. It works. Correctness comes first; readability of broken code is worthless.

2. It is easy to read. Next maintainer (human or agent) shouldn’t need to reverse-engineer your intent.

In practice

• Names carry intent. Variables, functions, and types should make the why visible. def s(x): is shorter; def schedule_retry(job): is the one anyone — including an LLM agent — picks up cold.

• Small, focused functions. Easier to test, easier to reason about, easier to compose. Agents refactor smaller units more reliably.

• No clever tricks where boring works. Clever code is fragile; the surprise factor compounds with every reader.

• Comments explain WHY, not WHAT. The code already says what it does. Comments earn their place only when they capture a non-obvious reason — a hidden constraint, a subtle invariant, a workaround.

• Consistent style. Pick a convention, automate it (formatters, linters), don’t argue about it in PRs.

• Type hints and schemas where they matter. Pydantic, JSON Schema, TypeScript types — they double as documentation that can’t lie because the compiler checks them.

The agent angle

Readable code isn’t just for the next human developer — it’s the substrate AI agents work on top of. An LLM agent reading clear, well-named code with strong types makes better edits, fewer hallucinations, and tighter PRs. Messy code degrades both reviewers.

Readable code ensures it works as expected and is easy for others — human or agent — to understand.