Is the purpose behind code being 'idiomatic' to reduce cognitive overhead?

Question

I'm trying to explain to someone that the way they've written the code makes it hard to understand, and if you refactor it then it's easier to read. This style of code I'm driving at is commonly called 'idiomatic' code'.

But the phrase idiomatic code brings with it baggage of moral correctness, which is not a great motivator to get people to change their coding style. A more positive way of saying this is code that follows the common style - but to a critical thinker that comes across as herd mentality reasoning.

The way I've come up with explaining this idea in a way that motivates people to change their code is:

• writing the code in such a way that it reduces the cognitive overhead of the reader (eg I can't remember if this is the first kind of vector - or the 5th kind of vector)
• code that makes it easier to understand the intent (eg what is this vector for?)

(As an aside, I'm aware the book The Joy of Clojure, prior to its first publishing, had the draft title Idiomatic Clojure. So it would seem a reason for making code 'idiomatic', to 'bring joy' to the reader).

My question is: Is the purpose behind code being 'idiomatic' to reduce cognitive overhead?

Answer 1

First, I'm not sure that there is any sort of "moral correctness" in the term "idiomatic". The plain dictionary definition is simply

peculiar to or characteristic of a particular language or dialect: idiomatic French.

Yes, idiomatic code generally reduces cognitive overhead, particularly at interface definitions where the standard libraries and any third-party libraries the project needs are (virtually) all idiomatic.

As a selling point, though, I'd focus on what reducing cognitive overhead does for you. It makes it easier for programmers to spot mistakes because they're not attempting to unravel code written in a unique style to figure out where it is subtly off by one or mishandling an edge case. It makes it easier to review other people's code which makes it more likely that the team will do real reviews that identify real issues rather than arguing about syntax.

Beyond reducing cognitive overhead, idiomatic code is generally more efficient code. Most idioms in a particular language evolve because the language is designed to approach problems in a particular way. The compilers or interpreters that you're using will focus their optimizations on idiomatic code. If you use a language where recursion is the idiomatic way to structure a piece of code, for example, you can be all but certain that your compiler implements tail recursion. If you use a language where recursion is non-idiomatic, that is much less likely. It's unlikely that tail recursion can't be implemented everywhere but most compiler writers aren't going to be focused on things that don't happen commonly.

Answer 2

I'm not sure where you get the idea that idioms have any moral connotations. Idioms are just a way to express things. They are patterns at a scale larger than individual words or phrases.

If I told you that one must howl with the wolves, you wouldn't know what I meant, even though that is a well-known German idiom. If, OTOH, I told you, when in Rome, do as the Romans do, you'd know immediately what I am talking about, because I used the proper English idiom.

Computer languages are no different.

Actually, an alternative name for "idiom" in the programming world is "implementation pattern". This relates the idea to the idea of patterns, which comes from the architect (brick-and-mortar not bits-and-bytes) Christopher Alexander. Most programmers know about Design Patterns, some know about Architecture Patterns, which are patterns on a scale larger than Design Patterns. Idioms are patterns on a scale smaller than design patterns.

Answer 3

Most languages intentionally lend themselves to a particular style. Code written in that style is what is idiomatic. If you look past the circumstantial fact that you choice of runtime environment narrows your available choice of languages, you should choose languages because the problem at hand is easy to express in the particular idioms of a language.

Most people don't get that though. For example, many Java programmers try hard to keep the same style when they have to write JavaScript (they could have written Java and cross-compiled it, mind you) and succeed to some extent - writing code that is Java-idiomatic in JavaScript - but they will always have the feeling of fighting JavaScript. Missing certain features or finding it hard to emulate them.

Idiomatic code is good. It is hard for the outsider, but they can learn. Ultimately, code has to be maintained for years, so if you can find a language within the idioms of which the underlying program can be expressed in plain fashion, that's what you should do.

Let me just clarify that there is definitely such a thing as overuse of idioms (or the underlying language features). If you use C++ templates to execute significant parts of the application logic at compile time, or if your complete Lisp program is a call to some macro that unfolds to the actual thing in practically unpredictable ways, if your Java solution of a simple problem inflates to the proportions of FizzBuzzEnterpriseEdition ... you're doing it wrong.

People say code must be easy to read. That's only half the truth. It must be easy to understand, which requires it to be easy to reason about also. That requires an adequate use of abstractions. As with most things, it's a matter of striking the right balance.