Good Code Matters

How many times have you found a code that looks really bad? You know what I mean, functions and classes are too long… the name of the functions and variables have not a clear meaning, blocks of code are unlimitedly nested… in short, the code is hard to read and it hurt your eyes.

And how many times after seeing that code you have realized it was written by… you!!

- NOOO!! That’s not possible, I’m the best programmer ever!! :-(

- Oh!! Off course you are… there, there… (little slap on your back)

But well, yes, if there is bad code out there that’s because, at some point in their life, a coder like you and me wrote it. It might be part of the learning path, or it might be that we wrote it when we were on a rush, on a tight release schedule, and then we were not able to come back to refactor properly. Or any number of reasons you might be offering to your inner voice.

However, you probably know that feeling… I would call it the “I-m-a-bad-programmer” remorse. I’m not sure if that is actually a “thing” in the therapist chair, I would need to gather a good bunch of programmer’s psychologists, girlfriends or pillows (as we don’t usually talk that remorse out loud), and ask them how often they heard that kind of auto-flagellation.

The thing is that bad code is not just a feeling, it has real consequences on the lifecycle of the system. During the first period of a project’s life, lines of code are piled by the thousands with the small team of coders carrying out the endeavor. But as the code base grow if the quality of code is not good the number of lines added on each iteration is less and less, because they are increasingly harder to add.

Just take a look at this paragraph I found somewhere on the web that illustrates the idea (He was a coder at a well-known database system):

“…What an unimaginable horror! You can’t change a single line of code in the product without breaking 1000s of existing tests. Generations of programmers have worked on that code under difficult deadlines and filled the code with all kinds of crap…”

If you ever felt that remorse, or if you think you can do better I recommend to read (or re-read) the book “Clean Code” from Robert Martin. On its pages, you will find a great deal of knowledge of what is Good code, and why it matters. From my perspective, the only problem with this book is that the examples are primarily focused on Java. However, it has a lot of good wisdom and advises.

That amazing Feeling

So, where all that bad code comes from? There might be a few scenarios where the bad code is intentional… Someone trying to show he is so smart that he can understand that cryptic block of code with those single letter variables… or maybe someone trying to keep his job the bad way, by writing code he can only understand and debug. Those scenarios exits, however, they are not so common these days (I hope).

What I think a more frequent reason is this: when we are solving a problem, our focus is set on the problem and whatever is needed to accomplish our goal. You probably have a good general idea on all the code changes required as soon as you read the requirement. And your mind is running way faster than your fingers… you want to finish coding and see it working! As on any hero’s journey, you will find obstacles in your path and monsters to defeat (like that external service API which doesn’t reply back as documented… sigh…). Finally, after all that mental effort, you are done, The machine is doing what you teach it… and there is that awesome feeling rising from inside, I did it! It works! I won!

Did you ever feel this way? That’s probably the reason why you love coding, and maybe why you became an Engineer (well that was my case at least). You are able to create something from nothing, and it works, and it solves a real problem. In occasions, you can even see the face of the person you worked for and realize how much of a help you are offering to him.

Ok, but now the system is working… why would you modify the code?… it’s working!! I live in Argentina, a country very passionate about football. Here there is a saying:

• “A winning team should not be touched”.

What that saying is actually saying is… What if I screw it up? Why should I modify something that is working?

And there is yet another problem, as your code is now working and the requirement is solved, now your client is asking for something else!! Of course, this is an endless game, the system is never finished, it can always have some additional feature, so we are always feeling the pressure to keep going, keep coding, keep adding things.

And this is exactly where the bad code starts to grow and spread. A couple of years has gone, and now you suddenly open a piece of code you wrote and BUM!… You experience that other feeling… the “I-m-a-bad-programmer” remorse. Your problem started right at the amazing “I-did-it!” feeling. Maybe even before, when you read the requirement and you automatically knew the path to the solution. Because you started by coding the solution… instead of writing your tests!

Test Driven Development

Test Driven Development (TDD), is not just a new fashion, is a solid and deep software principle.

The problem with the journey of the previous paragraph is that the hypothetical “you” started by coding the solution, instead of preparing a set of tests to make sure the solution is working.

When we are solving a problem, our mind is not focused on code quality, is focused on all the things needed to achieve our goal. And this is the right path, this is how it has to be. While working on the solution our mind can’t be also checking if the class has too many responsibilities, or if we are passing the right amount of data to a method. We are usually not sure if the name of the method will be clear enough, and so on. We just want to make it work and see the result.

If there is a good set of tests, we can go back once we are “done”, and start looking at the quality of the solution. We may need several iterations, and if we have a good set of tests, we won’t be afraid to make all the changes needed until it looks great. We shouldn’t be afraid to modify other sections of the application, even if they were not part or your change, in order to improve quality. Imagine working on a system which gets better and better with every release.

When we solved the problem, the code is just the first draft. Imagine yourself as a writer. You would never send your first draft to an editor and ask him to publish your book. You would read and improve your text in several iterations until you are fully satisfied. And then you would ask some friends to read it too and give you feedback (this is the code review).

A test is not just meant to make sure a future modification doesn’t break your code. They are meant to help you, right now, on all the iterations until your final, masterpiece of code. And this is when you call for a Code Review.

So what is good quality Code

There are many good principles you probably know. There are a lot of great books about quality code, and I would honestly appreciate your post of what is your recommendation in the comments below.

But I think there is one general simple guiding principle that can be applied and is the North we should always be looking for: readability.

When you are coding, the most frequent activity you are doing is not writing… is reading! For this reason, the most important thing you need to have in mind when looking at code quality how easy is to read it. That is… being nice with the future you, and any other future reader of your code. We are authors, we write for an audience, and it is very important to communicate well with them.

When it comes to readability you may think on comments. They are supposed to help us when reading our code, so if we are talking about readability, then this is one of the most important things to bring to the table. You are wrong. Comments are a necessary evil.

Some comments on comments

At some point, there was a lot of emphasis on the importance of good comments in the code. This was something almost every programmer dislike doing, but we didn’t really have a good reason for not doing it. Good comments sound like good advice, and when they are clear and complete, they really help to understand the code. So why shouldn’t we do it?

The thing is that time has past and we learned more about comments. They are usually forgotten when a modification is done, they also have a tendency to step away from the section they are documenting, and usually not deleted when the commented code is deleted. The reason is that with time comments become invisible. They are there but nobody pays attention because we can’t really trust them.

As comments can’t be trusted, when we really want to know what the code doing… what we do is… (you guessed it)… read the code. The most important document about the system and the one that can always be trusted is the code itself. Not the requirements, not the documentation, not the comments, the code.

So, we should never care about the comments? Well, we should… but as I said before they are a necessary evil. When there are things the code itself can not clearly explain, then it’s time to write a quick short comment that helps to clarify the idea. For example, when you have a regex expression is a good idea to add a comment with the kind of text this regex is for.

Naming things

We spent a lot of time creating new things… variables, classes, objects, methods, functions, etc. The name we choose for them has a big impact on readability. What’s the difference between the ProcessManager and a ProcessController?

The reason why it is so important is because, as we write, we are creating a new language for our system. When we create a method, we are saying, from now on this is how we are going to call this group of commands. We are literally inventing new verbs, with very specific meaning.

Some of the not-so-often followed rules for naming things:

• Acronyms are generally not a good idea. Remember you spent 90% of your time reading, so make it easy to read, not easy to write.
• Avoid using common programming element to name things in your application unless they refer to the programming element. For example, don’t call something ConnectionList, unless is actually a List. You can choose Group instead or something else.
• Avoid variations just to prevent a compiler error. For example, you name a class ProductInfo, just because there is already a ProductData class.
• In general avoid words which are just noise like Manager, Controller, Info, Data…
• If you work with a modern language and with a modern IDE, you don’t need Hungarian notation, it was created on a time when the compiler didn’t catch type issues.

Closing Ideas

I’m really only scratching the surface of this topic, it is a long and it’s not possible to cover all the aspects that matter when writing Good Quality code in a short article. There are specific design techniques which you probably know and use:

• Single Responsibility Principle.
• Open Closed Principle.
• Dependency Inversion Principle.

However, the most important ideas I would like you to remember are these two:

• Pay attention to your process… you won’t get it done right at the first iteration. You need at least a second pass, focusing specifically on quality. And you better have a good set of tests because otherwise, you won’t dare to make any change.
• Remember you are a writer, so focus on readability as much as possible. That will make the biggest difference in your results.

I’m very glad to work on a team who pay so much attention to code quality. My perspective is that this is a topic where you never should stop learning, as new knowledge and ideas keep helping us to be better Engineers.