Introduction to Clean Code

Posted in Coding
14/04/2020 Marc

Introduction to Clean Code

This post is inspired in Robert Martin’s video about Clean Code fundamentals.

The aim of this post is to show why Clean Code is so important. Having Bad code leads to a decrease in the productivity, provoked by a growing mess created in the code that makes it rot.

This will be the first of a group of posts related with Clean Code: how to write clean code, TDD, SOLID principles, …

The productivity trap

Anybody that has worked in a greenfield project has experienced the feeling of being able of producing features at high speed, of having total control, of knowing exactly which classes or methods would be affected by a new feature or change request. However… this feeling did not last too much, and productivity started to slow down.

After a few weeks or months, a mess starts to grow in the code.

Mess built in the code decreases productivity

The more that mess grows, the harder to add new features or modify existing ones.

The problem is not that developers are not working hard; the problem is that the code is slowing them down.

Brooks law

«Adding manpower to a late software project makes it later»

Fred Brooks in his 1975 book The Mythical Man-Month

In the short-term it is expected that by adding manpower to a team, performance will decrease, because original team members that produce must teach new resources, and this limit his production capacity. However in the mid-term, performance should increase, once new resources start to produce.

Expected increase of productivity

Nevertheless, this is not what happens. Productivity does not increase as expected. The reason is the people who is teaching the new people, is the people who created the mess. Not only the old people is teaching the new people: the old code is teaching the new people.

So, productivity is more similar to next picture:

The Big Redesign

«Given sufficient time, any group of programmers will decide to rewrite the code.»

Ron Lunde

After the mess, after the lose of productivity, after adding more resources… The team rebels and management accedes to the redesign.

The «Tiger» team is chosen. A group of programmers will be part of the redesign, keeping rest of programmers maintaining existing solution.

Where are the requirements? Of course in most of the cases there won’t be an up to date documentation, this means that requirements are in the code.

While the «Tiger» team works in the redesign, rest of programmers continue maintaining the solution, i.e. adding more requirements or modifying existing ones: the race has started!

The Race

Code rots

After some time code starts to rot. Following list shows characteristics of bad or rotten code:

  • Rigidity. Changes/fixes are incompatible with other modules. Rigid systems blow estimates.
  • Fragility. Small feature/fix causes malfunctions in one or many other parts of systems that have no connection.
  • Inseparabality. An inseparable system is a system in which those parts that might be profitably used in another system cannot be separated out from the first system. I.e. parts of that system cannot be reused in other systems.
  • Opacity. Reading the code tells you little or nothing about what the system does or the way it works. Opaque code is hard to read, hard to understand and hard to change.
Measure of code quality: WTFs/minute

Rotten code produces wild unpredictability.

The only reason the code goes bad is because we ruin it. We are the ones who made the mess. We rot the code.

But we got to go fast

It is unprofessional for programmers to bend to the will of managers who don’t understand the risk of making messes.

«Whenever you rush, you make a mess.»

Uncle Bob

How many times you have said to yourself: «But we can always go back and clean it later»? You know this means you are never going to go back at all.

Speed is an illusion. Shortcuts at the end are never short.

The irony is that making messes is not the way you go fast. It’s the way you go slow.

If you want to go fast, you have to stay clean.

Clean Code

What is Clean Code?

Following quotes are the definition on what is clean code from some authors:

“Clean Code is simple and direct. Clean code reads like well-written prose.”

Grady Boock

“Clean code always look like it was written by someone who cares.”

Michael Feathers

“I like my code to be elegant and efficient… clean code does one thing well.”

Bjarne Stroustrup

“You know you are reading clean code, when every routine you read is pretty much what you expected.”

Ward Cunningham

Programmers are authors

Code is read more than it is written (just think on your last edit session).

«Any fool can write code that computer can understand. Good programmers write code that humans can understand.»

Martin Fowler

The Boy Scout rule

“Leave this world a little better than you found it.”

Robert Baden-Powell

What if you did that with your code? Then code would get better and better.

It is not enough to write your code well. The code has to be kept clean.


«The only way to go fast, is to go well.»

Uncle Bob

Code is clean if it can be understood easily – by everyone on the team. Clean code can be read and enhanced by a developer other than its original author. With understandability comes readability, changeability, extensibility and maintainability.

Detailed rules to be applied to obtain clean code will be described in a next post, these are some of them:

  • Name variables, classes and methods to make them readable
  • Names should be pronunceables and searchables.
  • Functions must be small.
  • Funtions do one thing.
  • Whenever is possible, avoid comments, code should self explain