Clean Code

What is clean code?

Clean code as two words means very little, how can code be clean? We all know that code can be very messy in fact, we can look at some code, and it becomes the nightmare fuel for our future selves. So, what makes clean code then? In essence, clean code is code funny enough, that can be easily understood by others because in its nature everything is broken into small descriptive parts. Variables are adequately named, they make sense, they convey the meaning of their function. The same goes for functions, they aren’t big and bulky, but they are broken into small reusable pieces that also convey the functionality inside to the outside world.

Clean code isn’t something you simply stumble into, or you have to wait 10 years before you can do it. You actively have to fight the urge to produce poor code. There are deadlines, there are other people who output code faster, but you need to be the professional as Uncle Bob (Robert C Martin) would say. The professional programmer strives to produce high quality, clean code that contributes positively to the entire codebase, not slowly brings it down to an unmaintainable mess.

The biggest problem with clean code is that it’s hard to do. Each time you add code to the codebase you are making your codebase larger and worse, its entropy the slow constant decay. You have to actively fight this entropy, which is what makes it so hard. It's not enough to keep clean code in mind, you have to actively pursue that goal each day. The Boy Scouts have a saying, “Leave the campground cleaner than you found it.” Which is precisely what you need to do as a professional. Constantly improving the codebase to allow it to thrive, not to decay over time.

The core tenants of clean code

Following the conventions of the project

Every project has a convention, every language also has conventions. These conventions are rules and guidelines on how to you should structure, write and interact with the software. A professional programmer follows these at all times. It doesn’t matter if you don’t agree with how a language structures itself, you have to deal with it and follow it. There is nothing worse than someone who chooses their own formatting for a project compared to the rest of the team. It’s up to you to follow the principles of the language and what the team is doing as a whole.

Keep your code as simple as possible

Code complexity is the root of all evil. It produces monstrosities of code that no one understands, no one can change, and causes bugs. The more complex your code is, the more potential for bugs and the harder it is to change your code when you need too. You must write your code as simple as possible, so simple that you can come back to it in a few months when you have forgotten all about it and not swear at the creator of it, you! The developer who prides themselves on complex code is a poor developer and awful to work with in a team. The developer that can make the simplest code possible is truly the great developer.

Refactor no matter how small a tiny part of the area that you touch to improve the codebase overtime

Every time you pick up a ticket, in the end, refactor something that is of poor quality in the code base. No matter the size, it's good practice to be seeking places that could be improved and not saying someone else will fix it, but taking the time to fix it yourself. It can be one function, it can be a couple of variable names, it doesn’t matter what it is, only that it is improving overtime. My greatest achievement in my career is getting into a codebase which at that point wasn’t that great, it was complex, it was hard to deal with. I and another developer mapped out the biggest annoyances with the codebase, and we planned our small refactors to improve this over time. After six months of doing this we left the company and the codebase was spectacular. It was easy to refactor code, it was easy to understand what was happening, it was easy to test. We had an extensive test suite that highlighted any issues that came up when we refactored code, it was spectacular! You can implement the same process as you work. Making small incremental improvements that taken one at a time don’t amount to much, but given a long period of time will generate tremendous benefits for yourself and the whole team.

Never band-aid fix a problem, address the real problem not the symptom

You often come across a bug or a problem in your code that just doesn’t work properly. You spend a long time trying to figure it out, but at the end of the day, you still can’t figure it out. Don’t quit and say it’s too hard, keep going, reach out to others for help. You should never implement a bandaid fix unless there is an extremely valid reason to do so. It’s up to you as a professional to put in the work to implement a proper fix, not leaving it for someone else to fix later on.

How does it help?

Clean code is a lot of effort, so why should you bother. It makes your future self at the very least thankful that you didn’t leave them with a steaming pile of garbage for a codebase. Not to mention, the other members of your team will thank you when requirements change and your code has to be changed as a result. The cognitive load that can be refactoring, can be drastically reduced if the previous person made their code easy to understand and change.

Let’s look at some examples for context. In a clean code world, a function called `fetchUserNameFromUserObject(userObj)` wouldn’t require any further documentation because as a consumer of that function if I call it, I would expect a `UserName` field to be returned from a given object. I wouldn’t have to hunt around in the object or function to work out what to send it, I just send the user object and the username is returned. In an unclean world, the function signature might be `userName(obj)`, this is extraordinarily unclear as to what it’s actually doing. You might be able to infer that it's fetching a username, but it’s very unclear, is it going to return a value? What type of object do I send it? The goal of clean code is to convey the meaning of your code, the intention, or the work it is performing in as easy as possible to understand way, as you can. As a reader or a consumer of your code you should never have to dig through code or read several comments, which might be out of date anyway. You simply read the function name and the inputs, and it tells you what it does and what it should return.

The same goes for variables, naming them to something that conveys the right meaning, which will help the readers of your code tremendously.

Take for example the following

This means almost nothing to anyone who reads it to refactor this code.

This is a contrived example, the first code is very rarely to be written, although I've seen it. The second allows you, without knowing anything about `getUserInfoById` to conclude that given an ID, you will return user information. You don’t care where the data is coming from, you just care that you get the right data.

Making it easier for others around you and yourself is what clean code is all about. You wouldn’t write a novel and use made up words so that the reader is entirely confused. It makes no sense, to purposely confuse your read, of which you are one.

Resources that will help

There are several books I would recommend on the subject. My list includes the following.

• - Clean code by Robert C Martin

• - The pragmatic programmer by Andy Hunt and Dave Thomas

These are all invaluable resources that you should read cover to cover and many times over. I learn new things from these books every time I read them, and it’s made me better each time. These authors are some of the best in the field, teaching you how they approach problems, how they write code and how they conduct themselves professionally. This last part is of great importance, the field of software engineering is so new in the grand scheme of things that the field hasn’t had time to adjust to the gigantic influx of people. As a result, there are some awful programmers out there. Your job is to conduct yourself with professionalism and produce clean, well-architected code that can be read many times by others.

You can learn a lot from books, but you learn the most from doing. Writing clean and maintainable code is something that takes deliberate practice every time you sit down to write code. It won’t simply be, it must be practised, refined and perfected.