This is our first article in a series that will deal with the age old dilemma as to why developers fail. We aim to provide you with a few pointers on how to write a better code. For this, we will be taking a look at some of the most common mistakes that we, as developers, tend to make. These mistakes are not environment or language specific so this section is likely to be useful for almost everyone, irrespective of the environment they are used to working with. Here’s hoping that you find it to be useful as well.

Developers’ mistake #1: Writing code that is too difficult to maintain

Unfortunately, we developers have a habit of writing code that is more suited for the compiler than for the people who will actually be working with it. Examples, in this regard, are too many and we shall list only a few of them over here.

• Using a super-optimized expression that only the compiler is able to understand without any difficulty but an individual will struggle to comprehend.
• Writing a code structure where you can save space by omitting the brackets and braces. Okay, I am well aware of the sky-high prices for every GB of memory. Also you tend to write multiple instructions on the same line because the compiler will successfully interpret it in any case.
• You write a code that is split into several parts with each of them being in a different class. Then you interlink them with the help of chained calls or events. Sure, it looks very cool, but despite its claims to the contrary, that is not the right method to describe Separation of Concerns. Moreover, you are terribly complicating your code. You think anyone would be able to follow that?
• You make use of really explanatory variable names such as “n”, “i”, “res”, or “s”. Great, you have succeeded in saving some bytes. However, would it not be better if your variables had a name that was indicative of their role and followed some sort of rational notation principle?
• You are averse to the use of comments. After all, your code is very easy to understand and you can always execute it step by step. So good luck remembering why you wrote that particular method in the first place and did not use some other technique. Hope you do not have too much difficulty in explaining to your fellow developers the optimization you did for a really specific purpose of improving performance.

The real question behind these aforementioned examples is this: If a person has to read your code, will he be able to understand it? Will they be in a position to follow it straight away?

More importantly will you, as the developer, be able to understand what you have written three months from now? The compiler is programmed to understand and digest anything that you throw towards it but such is not the case with human beings.

Some people may feel inclined to disagree on this point. However, the most important criteria that defines a good code is not how optimized you can make it (yes, exceptions do exist) but how easily it can be maintained in the future. This depends entirely on the person entrusted with the job of writing the code and how easy they make it for other people to work with.

So it is my advice that you write code that is easy-to-follow and friendly in every way possible. Spare a thought for the people (and that includes you, mister) who have to read and understand it later on before they can support it. Forget about the language or the compiler, or at least don’t think about it more than you need to.

Oh, and make sure that you use the comments to good effect. Don’t just write anything for the sake of it, write comments that are meaningful. Don’t shy away from talking too much, it will only come in handy in the future. Have you heard that old joke that says that were the complete human genome to be decoded, 90% of it would come out as comments?

Well, simply go ahead and follow suit!