The Art of Readable Code

The Art of Readable Code is a book by Trevor Foucher, Dustin Boswell in which they argue that

Code should be written to minimize the time it would take for someone else to understand it.

The focus in on code (i.e. mostly at the function level) rather than at a whole program but is packed with many examples and very easy to follow. The authors provide a large number advices for improving the readability of the code including:

  • naming (variables, functions, ...)
  • how to provide meaningful (non-redundant comments)
  • simplifying the control flow and expressions
  • structuring the code

To give you an idea of why these advices are important based on my personal experience as a teacher. When I am called by students to help them fix a bug in their code, we almost always rewrite their code (together) following very much the advices from this book. Without that, there is no way I can understand precisely what their code does (and whether it does what it was meant to). Usually, once we are done rewriting it, the bug becomes obvious (to me and most importantly to them as well).

📘 The Art of Readable Code – Cheatsheet (generated by an LLM)

🎯 Core Idea

Readable code is code that clearly communicates its intent to humans first, machines second. It prioritizes clarity, simplicity, and maintainability over clever tricks.

1. Foundations of Readability

  • Clarity > Brevity: Short code isn’t always better if it sacrifices understanding.
  • Code is for People: Machines don’t care about readability—future developers do.
  • Minimize Cognitive Load: Reduce mental effort needed to understand code.

2. Naming Things

  • Descriptive Names: Reveal intent (maxUploadSize > x).
  • Avoid Ambiguity: Use precise terms (sendEmail vs. process).
  • Length Tradeoff: Longer names for larger scopes, shorter for local contexts.
  • Consistency: Stick to project-wide vocabulary.

3. Code Structure & Formatting

  • Order Matters: High-level concepts before details.
  • One Idea per Line/Block: Avoid overload.
  • Whitespace & Indentation: Use spacing to emphasize structure.
  • Align & Group: Visually cluster related code.

4. Functions & Logic

  • Short Functions: Easier to understand, test, and reuse.
  • One Responsibility: Each function should do one thing.
  • Readable Conditions:
    • Replace complex booleans with helper functions.
    • Use positive phrasing (isValid > notInvalid).
  • Avoid Cleverness: Readability > showing off.

5. Comments

  • Explain Why, not What: Code shows “what,” comments explain rationale.
  • Sparingly: Prefer self-explanatory code.
  • Keep Accurate: Outdated comments are worse than none.

6. Code Simplification

  • Eliminate Unnecessary Work: Don’t over-engineer.
  • Refactor for Simplicity: Break big problems into smaller parts.
  • Avoid Duplication: Consolidate repeated logic.
  • Progressive Refinement: Improve readability step by step.

7. Testing & Maintainability

  • Readable Tests: Tests should describe behavior clearly.
  • Defensive Coding: Anticipate misuse by future readers.
  • Refactor Continuously: Keep code clean as project evolves.

8. Mindset & Habits

  • Empathy for Future Readers: Write code for your “tired classmate.”
  • Iterate: First drafts aren’t the most readable.
  • Balance: Focus on reducing the biggest sources of confusion.

🚀 Key Takeaways

  • Treat code as communication, not just instructions.
  • Optimize for readability & maintainability in collaborative projects.
  • Apply principles in order: clear naming → structured formatting → simple functions → meaningful comments.
  • Always ask: “If I return in 6 months, will I understand this immediately?”