DEV Community

Kelvin Wangonya
Kelvin Wangonya

Posted on • Originally published at wangonya.com on

Writing readable code

Readability, I have been told, is not everything. Neither is breathing, but it does come before whatever comes next. — William Sloane, The Craft of Writing, (W.W. Norton, 1979), page 11.

Readability counts. - The Zen of Python

It's not uncommon to write code only you can understand, assuming no one else would have to read it, then come back a few months later to find even you can't understand what the code is doing.

crappy-code

Be kind to the person who's going to maintain the code you write in future. It's likely going to be you.

maintaining

A few tips on writing readable code

Do:

Indent properly

Some languages (like Python) are strict on indentation - which is good. Others may not be. Either way, make it a practice to indent your code uniformly such that it's readable enough.

Beautiful is better than ugly. - The Zen of Python

Read other people's code

This will help put you in the next person's shoes. If the code is readable, you'll, 1) get to see what makes readable code, and 2) appreciate the feeling of not having to struggle so much to make sense of things. If the code is not so readable, you'll learn what mistakes to avoid.

Limit functions to a single task, or to single and highly related tasks

As much as possible.

Have meaningful names for those functions

This actually builds on the last point. If functions are limited to a single task, it's easier to name them.

Write short descriptive comments

If necessary.

Don't:

Write comments reiterating code

It's much better to get in the habit of writing self-documenting code, and reserving comments for describing the plain-English intent of the code.

Be too clever

I don't know much about other languages, but I think Python is notorious for this kind of thing with its one-liners. I find these especially unreadable when lambda functions are involved. As elegant as a solution may seem at first, always consider the readability aspect.

Simple is better than complex. - The Zen of Python

Use magic numbers

Magic numbers are unnamed numerical constants that appear in the code. If you were writing a piece of code to shuffle the values in a list representing a standard pack of playing cards for example, it would be more readable to write:

deck_size = 52

for card in range(0, deck_size):
...
Enter fullscreen mode Exit fullscreen mode

It's very clear from the onset here that the number 52 represents the number of cards in a deck.

for x in range(0, 52):
...
Enter fullscreen mode Exit fullscreen mode

Here, we are left wondering where 52 came from. We'd have to dig more into the code to figure it out. 52 here may be considered a magic number. Not good for readability.

That being said, there are cases where the use of magic numbers is accepted. You can read more about that here.

Top comments (7)

Collapse
 
codemouse92 profile image
Jason C. McDonald • Edited

I probably sound like a broken record, but I'd like to suggest a change...

Don't: Write comments reiterating code.
It's much better to get in the habit of writing self-documenting code, and reserving comments for describing the plain-English intent of the code.

Collapse
 
wangonya profile image
Kelvin Wangonya

Thanks for the suggestion. I've made the change.

Collapse
 
titouansola profile image
Titouan Sola

Thank you so much for putting words over "magic numbers", it was so painful to try to teach avoiding something when you can't name it!

Good article ;)

Collapse
 
13roy profile image
13ROY

I agree, one thing I would add to "magic numbers" though is use constants, this way if you have such a "magic number" then you can share this across your whole codebase, keeping it DRY and easier to maintain.

Really good article and great advice.

Collapse
 
wangonya profile image
Kelvin Wangonya

I know the feeling 😄

Glad you found it useful.

Collapse
 
csorbamatyi profile image
Matyi Csorba

The Airbnb Eslint settings works the best for me. No more console.log and no more unused variables in codes.

Collapse
 
alexmacniven profile image
Alex Macniven

'Magic Numbers' is the best example of "It made sense to me at the time". Great suggestion 👍