How to Write Readable Code
Episode 9: Best Practices in the Field
(Last updated: 2025.5.02)
Readable Code
This article takes 5 minutes to read!
(If the image is small, try rotating your phone sideways)
In real-world projects…
So far, we've looked at techniques and principles for writing readable code: naming, function decomposition, comments, testing, and ease of modification.
In this episode, we’ll explore how to apply these concepts in real development environments—how to make them part of your team's workflow, how to reinforce them through reviews, and practical best practices from the field.
[Contents]
Success Stories from Real Projects
Practical Tips to Standardize Code in a Team
Key Points to Watch During Code Reviews
Checklist to Avoid Writing “Bad Code”
Summary
1. Success Stories from Real Projects
1.1 Easy-to-follow Batch Processing Code
A complex CSV processing routine was broken down into small, focused functions: “load,” “validate,” “transform,” and “store.”
By using the same terminology in both function names and log messages, the flow became easier to understand, and debugging was smoother.
Below is an example. The input CSV data looks like this:
CSV Data
The processing is handled using four functions and one controller function.
"Load" and "Validate"
"Transform" and "Store", and the orchestrating function
Here’s the output. Only the data for Alice gets registered; the others are flagged due to insufficient data.
Thanks to the clear separation and consistent naming, the process is highly readable and easy to trace.
Processing Output
1.2 Extensibility Through Data-Driven Design
This was introduced in the previous article.
Define things like discount rules in JSON and read them into your code. This means that future spec changes only require editing the JSON—not rewriting the logic.
The result is a flexible and maintainable system.
2. Practical Tips to Standardize Code in a Team
Below are some practical steps to help your team maintain consistent coding styles.
By using tools effectively, you can enforce good practices automatically.
Create a lightweight coding guideline:
Make it easily accessible (e.g., in README.md, Notion, or Confluence).
Focus only on essentials: naming, indentation, comments, folder structure, etc.
Use ESLint / Prettier / clang-format:
These tools automate formatting and linting, reducing the need for human intervention.
Be consistent with folder structures and naming:
Group by function, like components/, services/, utils/.
Use prefixes/suffixes consistently (e.g., ButtonList, UserService).
Use Git hooks to enforce formatting before commit:
Tools like husky + lint-staged can automate this step.
3. Key Points to Watch During Code Reviews
During code reviews, focus on “structure” and “clarity of intent.”
Let tools handle style issues so humans can focus on the deeper design and purpose.
This raises the overall code quality.
Is each function’s responsibility clear? Stick to one purpose per function.
Are names specific? Use intent-revealing names like submitOrder instead of handleClick.
Are conditionals easy to read? Keep nesting shallow and use early returns.
Are comments used where needed? Especially for explaining *why* something is done.
4. Checklist to Avoid Writing “Bad Code”
Here's a checklist to help avoid writing problematic code.
While these may be reviews of past points, each one is crucial.
Are names clearly expressing the intent of the logic?
Are functions short enough? (Guideline: under 20 lines)
Are there comments explaining the “why” behind decisions?
Are if-statements too deeply nested? Could you simplify with early returns?
Are there any unexplained “magic numbers”?
Is the logic reusable?
Is the design future-proof and adaptable to spec changes?
5. Summary
In this episode, we focused on real-world success cases.
In essence, writing readable code is a team culture that grows over time.
Through shared conventions, naming, structure, and reviews, the entire team contributes to maintainability.
Automate what you can, and let developers focus on design and intent.
The result is safer, faster, and more extensible software—a sustainable, continuously refactorable codebase.
Let’s aim for that kind of SDG-friendly programming.
▼ References
“The Art of Readable Code” by Dustin Boswell and Trevor Foucher, translated by Masanori Kado, O'Reilly Japan
