Ramblings About Clean Code

February 28, 2022 3 minute read

I learned to program in a bootcamp and together with all the introductory courses we had a brief lesson on high quality code. No matter how much I try, I can’t remember anything from it because of how vague it was. We tidied up some codebases in a typical Marie Kondo fashion and ridiculed some code samples with obvious flaws.

What I remember is the lecturer’s emphasis on clean code and the positive benefits of writing well. But I didn’t manage to establish a good understanding of what really makes a piece of code better than another one.

Many years later I’m still unsure what people mean when they argue about the cleanliness of an implementation. It’s a congratulatory statement similiar to “well-written”. You know it when you read something good but you can’t point out what exactly makes it that good.

I love Murakami’s little descriptions of the parsley on a character’s omelette but I don’t read his books just for that. The same way I love Neil Gaiman’s works but I can’t put a finger on what exactly it is that I enjoy.

It’s in the way the words flow on the page, but there isn’t a formula to follow.

In my hopes to get a better understanding and improve my own coding style I read the popular book Clean Code. I think it has some good timeless advice on functions, commenting and overall structure. But for every rule I wholeheartedly agree with, I found one I didn’t understand or disagreed with.

The truth is, coding remains a highly subjective activity and everyone will have their own definition of what clean means. The same way two writers can write masterpieces in completely different styles, two implementations can be considered clean even thought they follow different standards.

With that in mind, it’s clear how unproductive discussions about clean code can be at times. This is visible in PRs when an engineer requests a change to an implementation only because they consider an alternative to be cleaner.

Many developers use this argument when they personally don’t like a piece of code. That’s why I always ask for a specific reason or reference of a best practice when I feel I’m entering a battle of subjective opinions.

It’s good to provide alternatives, but we should rightfully label them as a personal preference.

Instead of thinking about cleanliness and elegance, when developing one should focus on incorporating the traits the implementation needs to serve its purpose. If it has to be modular, make sure it complies with that. The same goes with testable, extensible, reusable, loosely coupled or any other characteristic that comes to mind.

It doesn’t matter how clean it is if it doesn’t serve its purpose. And if it serves its purpose, does it matter if it follows a series of other arbitrary rules?

If we put the philosophical debates that senior engineers engage in aside, this is not an effective way to teach beginners about good coding practices.

Instead of passing down preferences that may not be useful in the next company a person goes to, it’s better to give specific knowledge and let people shape their own ideas around it. To outgrow the junior position, a person has to be able to create comfortably.

Subjectivity doesn’t help here, focusing on specifics does.

I often make comparisons with writing because that’s the closest activity to programming (to me), but even it falls short this time. You can notice dominant writing styles throughout the years but they take much longer to get established.

In software development, technologies change too frequently. A big part of Clean Code’s advice is inapliccable to React components even though they’re nothing more than functions.

But since I’ve mentioned that clean is a term that is up to interpretation, I should explain what it means to me. The main thing is whether the code can be understood quickly.

Understandable code can be maintained and it can keep the business running. As long as the systems are up and people know how they work I don’t mind if they don’t follow the numerous rules that make code clean.

I wouldn’t like to work with code that I can’t understand regardless if it’s written with all the best practices. And I say this as a person who is passionate about software design. Simplicity is more valuable to me both in writing and in programming.

I would advise you not to worry that much about whether your code will be considered clean but whether it serves its purpose.

To beginners I’d recommend studying the SOLID principles. To experienced engineers I’d recomment the book “Philosophy of Software Design” as a better source of programming wisdom. And to senior engineers I’d say to break out of established dogma applied without context.

Tao of Node

Learn how to build better Node.js applications. A collection of best practices about architecture, tooling, performance and testing.