Readability vs Idioms

We’re all here trying to add value. Trying to solve the problems we’ve seen. The problems that keep us up at night. Coming up with solutions that make a difference to something that’s important to us.

The question though, is not how to add the most value in the next instant, but how to add the most value over time. That’s and important distinction. Because what adds the most value right now might be different from what will add the most cumulative value tomorrow, next week, or next year.

You can see that in many different places. Helping someone else solve their problem instead of focusing on your own all the time. Taking many more much smaller steps in the right general direction as you figure out the correct path. Instead of just fixing a failure/outage/mistake, using it as an opportunity to make sure that a whole class of problems doesn’t happen again, or at least is much easier to isolate and recover from. It happens when you write new code and when you modify existing code.

Readability is a big part of that. You can solve almost any programming problem in almost any language. And you can make it look the same in all those languages. But should you? Is it really the most readable, most understandable, most maintainable way if you do it that way?

I’d argue that it’s not. Consider Go’s structs vs Java’s classes vs Python’s classes. At a high level they’re all about encapsulation. Keeping things in a domain together and separating domains. But they’re also very different. Java loves to inherit, but can compose. Go loves to compose and doesn’t have inheritance. Python has inheritance and composition, but doesn’t care. Java has a strict type hierarchy, which must be obeyed. Go and Python are duck typed. If you write the same code in all three languages it’s going to look odd in at least one (and probably all) of those languages to people familiar with that language.

That’s not good. No matter how readable code is in one language, if you transfer how you write in one those languages to another language it will NOT be readable. It might be decipherable, but we’re not looking for decipherable, we’re looking for readable, easy to understand code.

Of course, readability is one of those ilities. The non-functional requirements that creep into your requirements and guidelines. And like most of the ilities, there’s not a good, clear, objective, metric for how readable your code is. Given that, you’re never sure how readable your code is. So how can you know if it’s readable enough?

You can’t. so maybe there’s a better thing to focus on. Like guardrails. Guardrails that make it easy to do the right thing. Guardrails that encourage working with the system. Guardrails that make it obvious what is happening, and what isn’t.

And that’s where libraries and idiomatic code come into play. An example in Java is using Try/Finally. In Go it’s checking the returned error value. In Python it’s truthiness and falseness and comprehension. If you write with those idioms (and others) other people familiar with the language will see what you’re trying to do. They’ll know what you mean, what you’re trying to do, and the benefits and limitations of the idioms, libraries, and language features you’re using. By working with your languages and libraries you help yourself and anyone else who works on the code do the right thing.

Saying you’re doing something to make it more readable is arbitrary and subjective. Making it easy to do the right thing and hard to do the wrong thing is clear and objective. Don’t just ask people to be careful, make their lives easier.