Common Misconceptions About Clean Code

We have a huge wave of people who have started to code, which is great, but this also means we have a huge wave of misconceptions we need to clear as soon as possible before they spread too far. :D

There are several common misconceptions we have to clear out:

Clever Code != More Advanced Code

The truth is, if you encounter a relatively simple monolithic project, let's say with PHP and Laravel; or Node.js and Express, and you can't wrap your head around what is happening - that's normal - getting into a project written by someone else is hard, much more complicated than writing everything from scratch.

But consider this - if your first instinct is to rewrite everything and enforce some microservice + micro-frontend architectures - you are doing it wrong. Why? If you cannot handle monolithic architecture, what are the chances you will handle something much more complex? Yeah...

If you want to learn how to produce a clean code, make sure you have the basics covered, and you can turn around the existing project. You have a long road ahead if you can only work with a perfect codebase and don't know how to turn around a bad codebase (short of rewriting it from scratch).

Shorter Code != Cleaner Code (aka "you don't know how to measure complexity")

Please, for the love of God, do not try to pack your entire code into as few lines as possible. That makes it less readable.

If you focus on the shortest code, you essentially do a Code Golf - not a clean code.

The most basic way to measure code readability is to use Cyclomatic complexity - which tells how many control statements there are in your code. The more there are - the harder it is to follow what is happening.

Clean Code === Maintainable Code

Another way to measure code cleanliness, however more time-consuming, is code maintainability.

If adding the 10th feature to the codebase takes more time than adding the first few features - the code needs to be cleaner.

If any changes introduced to the project by the business owners prompt a rewrite or take weeks to adjust - the code is not clean.

Clean and maintainable code means that it is possible to add, remove, and change features at a consistent speed, no matter how many of them are there in the codebase.

You Can't Learn How to Write a Clean Code (not directly at least)

You can't - you can learn how to imitate it, but please just don't set yourself a goal of writing a 'nice looking', clean code. Instead, focus on maintainability and simplicity. Don't focus on writing 'less' code, either.

You can practice this by doing pair programming. Write some code - ask someone else to read it back to you and ask how they understand it. Note whatever spots were unclear, and correct them. Focus on readability, simplicity, and maintainability first - producing a nicely-looking code will come by itself with time.

Thinks About Others First

Programming is a team effort. Refrain from thinking about how your code will look - I guarantee you that with that attitude, it will most likely be garbage.

Senior developers can 'read the room'; they understand their colleagues' capabilities and skills, what the team intuitively understands, and what patterns work in the project. Make it about others - try to make other people's work easier. In a team where everyone has such a mindset, work is a pure joy and pleasure, and it's just lots more performant.

What code is "cleaner"? The one you think is clean, or the one that everyone else in the team can easily read and maintain?

Summary

If you are to take anything from this article, do not try to make you and your code look good. Stay humble and consider how much difficulty other people will have with reading and understanding your code. Yes, this means that sometimes you have to get a team's "buy-in," and this sometimes means that you have to pause and explain your ideas to others to get everyone on board - which is equally important as just coding something.

The code is only clean if everyone on the team thinks it's clean.

The sooner you learn that it's a team effort first and foremost and not about flashy and clever tricks, the sooner producing clean code will come naturally to you.