Some tips to improve your codes readability

January 20, 2013

What about code readability, from my point of view is one of the most important thing in the code. Who writes code that is easy to read, writes good code. Probably reading code is where you spent most part of your time, and not only your code, probably code of your team mates, or maybe code from the open source community, so write code that is simple and is easy to understand it’s really important.

How write code that is easily to read?

Well, it’s not that simple, but there are some tips, that you can follow, I’ll try summarize some of these tips, to help you to write better code, and increase the code redability of your code.

Tip 0: Comment before write your code (DocBlock)

What? Before?? YES! let me say why…

When you came with the idea that is needed a new method or a new class, we normally starts create the code for this class/method, but probably the main idea of what your method or class will do, you already have in mind, so why not describe in a comment what the method/class will do, before you start write real code.

Some of advatanges that you will get putting this in pratice:

Tip 1: Return frequently, Return early

This tip is quite simple and help a lot increase the readability.

What does it means?

It means that always when possible, you will be returning something from your method.

Some of advantages that you will get putting this in pratice:

Example

Tip 2: Break, Continue

Loop, we love repetitions, but a good tip is leave early from a loop.

To do such a thing we have the break and continue, so always that is possible try to use these commands, these commands will help avoid the usage of the else condition, and it will also help you split into other pieces your code… You will be able to delegate code for other methods. Your code maybe will be also fast, as the fact that probably it won’t be needed to pass all the block of the loop, it will leave the block early.

We can do:

Tip 3: Code Standard / Name conventions

Use code standard, follow rules in all your project, it does not matter what code standard you will pick, but follow the rules. It also applies for the Name Conventions, try follow a name convention, not use abbreviations, pick good names for your variables and methods.

Define how will be indent the code, define a column limiter, and follow those rules… You can check a bit more about code standard, in my other post.

Try to keep some standards, like set and get, normally when we see set and get in the code, we think that this method will access properties of the class, so try to not use these prefixes, when your method will not just accessing the properties of class, use other more descriptive names.

A good way to think, is read the action. For example:

Try read the code… “User get the User 1” sounds strange… so when you are reading the code, you will get a good overview, try approximate as maximum as possible of our natural language.

So for the example, a better approach would be:

“User Manager get user by ID X”

Try to avoid replicated the name of the instance class, that you are using in the methods, when you have the instance of the class (the object), you will already have the user, so no make sense repeats the user nomenclature a long of the methods…

Other things that you can take care is the prefix/suffix:

Try keep consistence between the methods… if you use has and is, try follow in all other classes that nomenclature and also the kind of data that it will return.

Tip 4: Throw Exception

Try throw one exception always that it’s possible, some advantages of this is that you can stop your code, so if you have a big block of code when you throw the exception, the code will stop there.

Another advantage of Exception, is that you can write in natural language, instead of use boolean, true or false, when you are using one exception you can say exactly what was that happend when the exception was trigged, so when you are reading the code you can quickly identify what happend, and you also gives the possibility to handle that exception in the way that you want to.

Tip 5: Comment often, but not write stupid comments

Comment the code, as mention in the Tip #0, it’s good, not only in the Doc Block, but all over your code, it gives for the programmer a good overview of what the follow code will be doing…

But please, you don’t need to comment everything and also you don’t need to be stupid.

You don’t need to write stupid comments, put your comment where is needed! In complex logics, or big blocks of conditionals. But always try to summarize the points, try think in a way that when somebody reads your comment this person will really get a good insight of what will happen in the follow lines.

Tip 6: Methods can be always smaller than they are

Try always to break into minor pieces your method, decouple your code, reduces the complexibility, delegate logic for other objects, for other methods, it will help a lot in the readability, instead of a complexly block of code you will be able to just ask something for a method… Try to not create magical methods that does everything, each method, each object can do a part of the whole process…

Using this in pratice, it will help to test your code, it will be more simple to guarantee that a specific thing is working, because each method and object will have a properly role, not a super magic one…

To summarize

Take care of what you are writing, try always to think if another person reads your code if they will understood, try to make consistent code, a consistent API, follow the rules.

And I recommend to read Object Calisthenics, it will help you write better OOP code, and also code that it’s more easy to read.

Discussion, links, and tweets

Hi I'm Vinícius Krolow. I'm a software engineer at Conrad Caine. Follow me on Twitter; You will figure out how cool I`m :P

blog comments powered by Disqus