Clean and Bias

The problem with "clean code" is that it is so subjective. It can mean surprisingly different things to different people. Viewed through the lens of our unique experience, perception and sets of bias, the same code can appear flawless to one person but obscure or puzzling to another. When this becomes a problem - when agreement must be reached - the solution is to be objective.

An Example

Here's an example of a questionable use of "cleaner". It's a snippet from an otherwise excellent overview of Combine. Just a few lines of declarative Combine (like my own FetchTask) can replace multiple files and asynchronous callbacks to greatly simplify an otherwise complex flow. It can be used to write "cleaner" code. But this code... doesn't show that very well.

import Combine

let simplePublisher = [1, 2, 3, 4, 5].publisher

var cancellable = simplePublisher
    .map { $0 * 2 }
    .sink { value in
        print("Received value: \\(value)")
    }        

If you want to print "2, 4, 6, 8, 10" I suggest that the for loop below is "better". Specifically, the loop is a single line, 5 lines less code. And while Combine is very powerful, it does have a significant learning curve. Readers unfamiliar with the framework won't know the concepts and may be a while deciphering the code. Even readers familiar with Combine will take at least a few more seconds to puzzle through the above snippet. The snippet below requires only a basic understanding of swift.

for i in 1...5 { print(i * 2) }        

Is the first snippet "bad" or a "code smell"? Well no, I don't see any need to offend someone by calling their code stinky. Both snippets produce the same output. One is just a bit shorter and requires less knowledge. Unless I missed something, I would say the second is "better".

What is clean code anyway?

Clean code is easy to change. That's a summary of an already short tweet by Uncle Bob. There is a wealth of detail on specifics - courses, definitions, and many more articles. But the one sentence version is this: clean code is easy to change.

When the customer wants a feature or bug fix, the faster you can deliver it, the better. I love when I can smile and say "that is an easy change, one hour of coding tops". I dread when instead I must say "we didn't design for that, we'll need a few months".

The code base allows you to deliver a feature or bug fix faster is better. It is cleaner.

Why don't we always agree on clean code?

There are several reasons why we don't all perceive the same code the same way.

Our perception is actually much worse than we think. Amy E. Herman states in Visual Intelligence: "... our brain cannot and should not process everything we see. If it did we would be overwhelmed with data. ... Our brain automatically filters our surroundings and allows only a small percentage of information to pass through ..." [1, p. 88].

To make matters worse, we are subject to various kinds of egocentric bias which make us to overestimate our perception. We believe we've processed all relevant data and can recall it with high accuracy. When in fact we routinely miss the surprisingly obvious. One example is a famous selective attention test.

Still not convinced? Here is another great example from Visual Intelligence [1, p. 90]. Read the sentence below just once, counting all of the F's:

ARTIST FABIO FABBI PAINTED DO-

ZENS OF DEPICTIONS OF ORIENTAL

LIFE ALTHOUGH HE WAS OF ITA-

LIAN HERITAGE HIMSELF.

Many will count four or six F's. When I first read this example, I had to re-read several times in disbelief before I got the correct answer: seven.

Putting it all together, it should be no surprise we may disagree on whether code is "cleaner". We're all perceiving only a small percentage of out input. The odds are small we're seeing the same thing to begin with. Mix in our bias that our perception is correct, and others are wrong. Then top it all off with different experience and our other sets of cognitive bias.

Viewed through all those lenses, the same code can appear very different. No wonder there are disagreements, we're probably not even talking about the same thing anymore.

Is "clean disagreement" a problem?

Whenever code is shared, there will probably be some related issues. The code base may become inconsistent. There may be churn as each developer rewrites to make the code "cleaner". There may be some understandable tension and stress when reviewers starting throwing around the phrase "code smell". Justified or not, that can't help but feel like a personal attack. That has no place in a code review.

Solution: Experience

One way to address differing experience is to use a shared experience. Write and use a set of coding guidelines. Start small, capture the highest priority patterns, do's and don'ts. Refer to the guidelines while writing and reviewing code. Update as necessary when new issues arise. But do keep the guidelines concise: too many will discourage use and defeat the purpose.

Solution: Perception

As to our limited perception, well, just being aware of it should help a little. We are all human and make mistakes, remember that you may have missed something. Beyond that, our perception can be trained and improved. Try reading Visual Intelligence [1] and similar books and courses. Our perception will never be perfect but every bit will help us understand others better.

Solution: Be Objective

Finally, we can help others understand us by keeping the above in mind. Again, Visual Intelligence offers help: prioritize and be objective. We know readers perceive only a small percentage of their input, so put the most important information first. And keep your information concise.

But more importantly, when assessing quality of code, be objective. Discuss independently verifiable aspects of the code, like number of lines, running time, patterns used. Avoid subjective value terms like "clean" or "smell". Used without supporting arguments, we've seen how unlikely it can be that others will agree with the value statement.

References

1. Herman, Amy E. (2016). Visual Intelligence. Boston: Houghton Mifflin Harcourt.