Tinselcity

On transcending clean code

The other day someone posted his own article to reddit, about abstractions, or about clean code, or about breaking code, or about his own anecdotes.

The following was my comment1):


Maybe, instead of pretending to extract absolute truth from an anecdote, actual understanding should be acquired…

Abstractions are generally good. And having multiple repetitions of large amounts of code is generally bad. Having cleaner code is generally better than having dirtier code. But for all those there are circumstances that must be taken into account.

The mistake here wasn't abstracting per se, it also wasn't not talking to the original developer, or even a matter of beauty, of trust, etc. The mistake was that the “refactorization” only focused on the code and not on the circumstances. He saw some code, ignored everything else, decided to mess with the code.

If we ignore this point, little can be really learnt from the stereotypical anecdote. And in fact, this, the lack of an actual conclusion, the non-sequitur in the argument, is the most salient point in the original article.

Code fulfils some needs. It never exists for its own good, but to achieve some goals. The author was thinking about the code, but not about the needs. To modify code successfully… particularly: to refactor code successfully, we need think about the needs more than ever. Because when we refactor some code there are no new requirements, no new needs to provide, other than “making the code better”. It has to do exactly what it is already doing, but with some added qualities that make it “better”… in some sense.

So we need to know what the original needs were, because otherwise we won't know if what we think is “better” actually is.

We should ask ourselves some questions about the subject code. Is that code supposed to be used frequently? Modified frequently? What kind of modifications? Which requirements will likely change? Is this code long- or short-lived? Will this code expand (as in will more copies appear if we go on this way)? Or is it bound to disappear anyway (as in in a couple of months three out of five of the cases will be deleted)?

In fact, the first question we should be asking ourselves is: “Does this code need to be better in any way at all?” Because if it doesn't then you're pushing code into production just because of your own personal whim. Of course, if after understanding why the code is the way it is, you do identify an opportunity to really make it better, by all means do it.

The problem is the article is too close to being misguiding, not so much because it defends any particular position but because from the stereotypical anecdote nothing is really learned other than “let it [clean code] go” and that's not really a progressive2) conclusion. It's not really something that helps.; it fails to explain and provides no solution. If clean code in itself was not the important part, then what is it? And this is where the article comes really short. It fails to point where to go next, while making a bunch of broad statements that easily can -and will- be taken wrong by many less-experienced people.


One thing I didn't comment was on the subject of “asking for permission” and “code ownership”. I left those two things out because they are mostly boring discussions. But as some other commenters brought it up a number of times, I will add that the part where you go and find those circumstances of the code, why it is the way it is, will lead you to talk, but not in the sense of asking for permission from the original developer, but in a much more natural and productive way: it will lead you to a conversation about the code, the development process, the workflow, problems… Things which are always good to talk about.

There's also some ambiguity regarding the original reference. Did they mean clean code or Clean Code? As in the general idea or the particular book? And I guess it's a common confusion. A lot of people seem to associate both too tightly, and while one might dislike or have certain criticisms on the book and on the author, despising the concept itself of keeping your code “generally clean” sounds like a silly affectation or a pose.

1)
with a just little more polish/detail
2)
as in progressing, advancing, improving, learning