Why It Matters the MOST
What is it?
Code Readability at its simplest definition means that the code is easy to follow,
Why is it important?
Source code is designed for us. It may end up being processed by a machine, but it
evolves in our hands and we need to understand what the code does and where changes
need to be made.
When a developer initially writes the code their knowledge of the system is very detailed
because usually they have worked on the project for some time, read requirement/
technical specs. They know the code/related code, they know the system, everything is
6 months or a year later no one is going to know the system that well again, so you have
to understand how the code works by reading it.
Poorly written code can make this very difficult, code with poor readability is
• Difficult to understand
• Longer to debug
• hard to maintain
• tricky to extend
How to improve it?
Below are some tips to write readable code.
1. Standards of indentation and formatting are followed, so that the code and its
structure are clearly visible.
2. Variables are named meaningfully, so that they communicate intent.
CODE READABILITY 1
3. Comments, which are present only where needed, are concise and adhere to
4. Guard clauses are used instead of nested if statements.
5. Facilities of the language are used skillfully, leveraging iteration and recursion
rather than copy and paste coding.
6. Functions are short and to the point, and do one thing.
7. Indirection is minimized as much as possible, while still maintaining flexibility.
How to determine if your code is readable?
You cannot determine this yourself because as the author, you know more than the code
says by itself. A computer cannot tell you, for the same reasons that it cannot tell if a
painting is art or not. Hence, you need another human - capable of maintaining the
software - to look at what you have written and give his or her opinion. The formal name
of said process is peer review.
Below is an example of two snippets of code, while the first was written ignoring the
readability aspect of the code, the second snippet adhere to many good code readability
tips. Hopefully you can easily follow the logic in the second code unlike the first one.
for entry in item:
CODE READABILITY 2
eType, eValue, eTraceback = sys.exc_info()
print >> sys.stderr, time.strftime("%Y-%m-%d %H:%M:
item_approved = (item['approved'] == '1' and item['active'] ==
db_item = item.get_db_record(item['id'])
db_item = item.create_db_record(**item)