6 tips to create a more readable code

I am usually tough with myself in everything I do, writing code is not an exception. I always have in mind the person that is going to come after me and is going to read the code I wrote, trying to understand it. Truth be told, I also hate to read complicated and unreadable code, so I usually try to make mine as clear as I can.

In this post I gathered the main rules I follow when coding. Hope one of this tips can help you in some way as they help me when writing my code.

#1 LET'S KEEP METHODS SHORT

When reading an unfamiliar code, we are most likely to read through that code. In that situation, we look for small pieces to focus our attention and comprehend the reading code in detail. Keeping methods short, focusing in short and concrete functionalities, will help the code reader to smoothly understand our code piece by piece.

Example:

The above image shows a really long "init:" method. The block of code is agglomerating several initialization processes that is difficult to get at first sight.

Breaking the code into small functions, will let the reader to discern our code and understand its overall content at first glance.

Using this approach, the reader can read later on each function, only if necessary.

#2 LET'S THE CODE BREATHE

As in graphic design, white spaces help to improve readability. In addition, they give focus to an object/code and directs the viewer's eyes. Based on that fact, adding blank/white spaces in concrete locations inside our code will help the reader to understand easier its programming purpose.

Example:

The above code has no spaces, it's not easy to identify where starts one process or another, even less identify the different operation code blocks.

Adding blank spaces between operations, lets the reader to easily discern the different programming steps and functionalities inside the same method. Plus it becomes clearer at first sight.

#3 LET'S WRITE CLEAR NAME PROPERTIES / METHODS

"Code should be as easy to read as a book". This is something I learned during the Try Swift conference of 2016 in Tokyo. In other words, we should not be afraid to write long and descriptive properties or name methods. Clearly specifying the purpose/functionality of the variable/function should help the reader to have a better understanding of our entire code when reading.

Example:

The above image gives and example of how I usually name properties. The property names not only clearly specify what they are, they also indicate their type.
Based on a guidance a university professor gave me several years ago, I usually write the type property at the end of its own name. In short classes or small projects this idea may seem pointless, eventhough when working in big or long classes, knowing the type of the property by the name can be really useful and clarifying.

#4 LET'S COMMENT SPECIAL CODE CASES

Even if we try to make our code clear, there are cases in which our code is not going to be explicit enough. That is for example, when in a hurry, we add a temporary amend to a specific bug and we create a special code case that doesn't make sense in its context. In that situation, an external reader is most likely to get lost in our code without a proper explanation. Therefore, explaining special programming decisions through comments should make our code also readable at critical points.

Example:

You can eat an ice-cream through your mouth or through your nose, obviously through your nose would be difficult and painful, but there is no reason you cannot do it. In that case, would be of help if you let to know the reason of your choice to the people around you. 

#5 LET'S INDEX/MARK CLASSES FILES

As noted previously in this article, when reading an unfamiliar code, we are most likely to read through that code, but reading through long code files can result quite tough. What if instead of reading through it, we skip the "unimportant" parts and we focus on what we are looking for. Indexing/marking classes can help to easily access to a specific piece of code without the need to go through all the file. Indexing classes cannot only help external readers, but also can help ourselves to rapidly find code and make changes or adding new functionalities. 

Example:

The above image shows a really long class, with lots of properties and functions. Finding a specific piece of code inside this class is going take a lot of time, unless we are really familiar with that code, and we know in which scroll position is what we are looking for.

Indexing/marking the file class creates and easy access to any part of our code. Specially if properties and methods names are explicit enough, external users don't even need deeper reading in our code, they just can focus on what they are looking for.

#6 LET'S USE INTERFACE BUILDER

' "A picture is worth a thousand words" is an English idiom. It refers to the notion that a complex idea can be conveyed with just a single still image or that an image of a subject conveys its meaning or essence more effectively than a description does.' Wikipedia

Based on that statement, if we use storyboard and interface builder it will help in the purpose of packing thousands of user interface design code lines into a single file/image. This approach will result on having less code inside our classes, and as a consequence our code would be shorter and clearer. 

キケ