Why It Matters the MOST

What is it?

Code Readability at its simplest definition means that the code is easy to follow,

logically.

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

in harmony.

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

standard formats.

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.

Unreadable:

try:

if item[1][2]=='1':

qtytype='0'

qty=str(item[1][0])

items=item[1][0]

amt='0.0'

tot_amt=str(float(item[1][1])/100)

# tot_amt=str(float(int(item[1][0])*int(item[1]

[1]))/100)

else:

qtytype='1'

items=item[1][0]

amt='0.0'

tot_amt=str(float(item[1][1])/100)

qty=0

for entry in item[1][4]:

qty+=entry[0]

CODE READABILITY 2

except TypeError:

eType, eValue, eTraceback = sys.exc_info()

print >> sys.stderr, time.strftime("%Y-%m-%d %H:%M:

%S"), str(traceback.format_exception(eType,eValue,eTraceback))

Readable:

item_approved = (item['approved'] == '1' and item['active'] ==

'1')

if item_approved:

try:

db_item = item.get_db_record(item['id'])

except DoesNotExist:

db_item = item.create_db_record(**item)

item.approve(db_item)

db_item.save()

publish_event(item.events.APPROVAL)