The Key Lessons from The Art of Readable Code

Introduction

#

This article summarizes the key lessons from The Art of Readable Code.

View The Art of Readable Code on Amazon Japan

1. Write Code That Is Easy to Understand

#

• Good code can be understood by someone else quickly
• Optimize for comprehension, not line count

2. Pack Information into Names

#

• Choose precise words: prefer verbs such as Fetch or Download over a vague name like Get
• Avoid generic names: short-lived variables such as tmp are fine when their purpose is obvious
• Be specific: make it clear what a value represents
• Include important details: add units or attributes, as in start_ms
• Match length to scope: reserve short names for small scopes
• Use formatting consistently: give capitalization and underscores a clear meaning

3. Choose Names That Cannot Be Misread

#

• Use max_ and min_ for upper and lower limits
• Use first and last for inclusive ranges, and begin and end when the endpoint is excluded
• Prefix booleans with words such as is or has

4. Make Code Visually Clear

#

• Keep indentation consistent
• Present related elements in the same order everywhere
• Split large blocks into meaningful paragraphs with blank lines

5. Know What to Comment

#

Do not comment:

• What is already obvious from the code
• Confusing code that should be rewritten instead

Do comment:

• Why a particular approach was chosen
• TODOs and known issues
• Why a constant has a particular value
• The purpose of a file, class, or block of code

6. Keep Comments Accurate and Concise

#

• Avoid ambiguous pronouns such as “this” or “it”
• Describe the code’s intent precisely and briefly

7. Make Control Flow Easy to Follow

#

• Put the changing value on the left side of a comparison and the stable value on the right
• When possible, handle positive, simple, or prominent conditions first
• Avoid ternary expressions, do/while, and goto when they make the flow harder to follow
• Use early returns to reduce nesting

8. Break Down Large Expressions

#

Use explanatory variables to split large expressions and code blocks into meaningful pieces.

9. Use Variables Carefully

#

• Remove variables that do not simplify an expression, clarify meaning, or eliminate duplication
• Keep variable scope as small as possible
• Prefer immutable variables

10. Extract Unrelated Subproblems

#

• Separate general-purpose logic from project-specific logic
• Too many tiny functions can also hurt readability, so extract them when reuse becomes necessary

11. Do One Thing at a Time

#

• Let each block of code handle one task
• When several tasks are mixed together, list them and separate the distinct operations

12. Turn Thoughts into Code

#

Explain a complex idea in simple language first. Too much detail can hide the real intent.

To make code clearer:

1. Explain what the code does in language a colleague can understand
2. Identify the key words and phrases in that explanation
3. Write the code to match that explanation

13. Write Less Code

#

More code means more maintenance. To avoid adding unnecessary code:

• Remove unnecessary features and avoid speculative functionality
• Find the simplest requirement that solves the problem
• Learn the available APIs and standard libraries so you can reuse existing solutions

14. Make Tests Readable

#

• Write failure messages that make the cause easy to identify
• Code designed for easy testing tends to have clearer responsibilities