Thursday, September 20, 2018

The Readability Lament and How to Handle It

This week, I've written a lot about readability. It isn't really a property of code. It's actually a quality of an observer's experience when working with code. Yet it's very, very important.

The combination of potency and interpretive license provides a potential exploit for developers resisting the adoption of technical excellence. Just say "that's not readable".

Three little words offer a wealth of power to anchor-draggers. That power runs counter to the interests of a team. Honestly, it's not doing the resistors any favors, either.

Thankfully, it's not too hard to defang this claim.

The solution is actually quite simple but represents a moderately-difficult shift in mindset. Instead of treating all code quality problems as a problem with code, start by treating them as a deeper problem that resulted in a problem with the code. Also make sure the audience is always declared by asking "To whom?"

If everyone is always open to a coding problem being a symptom of something else and accepts that readability is observer-relative, then you can start to have honest conversations about readability. In those conversations, you can ask questions like...
"What's so un-readable about having an extra layer of abstraction there?"
"Does everybody think that's unreadable?"
"Why do you think it is?"
...and we can keep asking those questions until we get to something actionable and mutually beneficial.

Sometimes, the answer really is "That code is just plain abstruse and you should write it in this simpler way." Sometimes, the answer is going to be that one or more people on the team needs to adjust their mindset or upgrade their skills.

Whatever the outcome, you've got a better shot at finding the real problem with honest (if difficult) conversations about who finds code to be unreadable and why than you do with abstract labels thrown around on a whim.