Code Must Be Clean. And Clear.

There is a famous book by Robert Martin called Clean Code.
The title is an obvious call to all of us: the code must be clean. Clean, like a kitchen,
I suppose—there are no dirty dishes, no garbage on the floor, no smelly
towels. Dirt to be cleaned in a code base, according to Martin, includes
large methods, non-descriptive variable names, tight coupling, lack of
SOLID
and SRP compliance,
and many other things. Read the book, it’s worth it. However,
there is yet another aspect of source code. How clear is it?

The kitchen is clean when there is no dirt in the oven. But if its electric panel
speaks French, I can’t use the kitchen. Even if it’s perfectly clean.
It’s not clear how to use it—that’s why it’s useless.

The metaphor applies to the source code. Making it clean is the first
and very important step, which will remove all those coding anti-patterns
so many books speak about, including my favorite
Code Complete by Steve McConnell,
Working Effectively With Legacy Code
by Michael Feathers, and
Clean Code.
A very important step, but not the most important one.
A dirty kitchen that is useful is better than a clean one that I can’t use, isn’t it?

Making code clean but leaving it difficult to understand by others is the
pitfall most of us fall for. By others I mean everybody, from
our fellow in-project co-developers sitting next to us at the same desk, to
imaginative junior contributors who will join the project in five years after
we’re all hired by Google. All of them, across this very large time frame, must
be able to use the kitchen source code without any additional help.
The oven has to speak their language. Not the language of its designer.

How do you do that? How do you make sure the code is clear, not just clean?

Well, test it. Ask someone who is outside of the project to take a look
at your code and tell you how clear it is. Not how beautiful your classes
and code constructs are—that’s what makes it clean. Instead, ask someone to
fix a bug in just 30 minutes and see how they react. You will realize
how clear the code is and whether it speaks the language a stranger
can understand.

This is the definition of maintainability. If a stranger can modify your
code and fix a bug in less than an hour, it is maintainable. Obviously,
cleanliness will help. But it’s not enough. There has to be something
else, which I don’t really know how to describe. The only way to achieve
it is to let strangers regularly see your code, attempt to make a
contribution, and report bugs when something is not clear.

Making your code open and encouraging programmers to report bugs when
something is not only broken but unclear—are the best two ways to achieve
high maintainability.

How do you feel when your buddy says that your code is crap? #codeahead