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?

  • My typical comment, vis à vis reading code, is that you write code for at least two compilers: The other people, including yourself, that have to read the code later. And the process that your run via Ant, Make, or an IDE. The first one is more important.
    – user156792
    Commented Jan 22, 2016 at 0:06

3 Answers 3


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.

  • 1
    Your answer, quite reasonable, inspires this reaction: Idiomatic French, from Paris, Montreal, Cote d'Ivoire? Code is not so different. There is no idiom without community. If you sound like from Montreal, you can expect to cause a little 'cognitive overload' in Paris. Probably the world will always be divided between those who think there is a single right way (Python?) and those who say Vive la différence! (Javascript?). Now, if we want to write Javascript idiom that compilers find more efficient, let's all write like a minifier/uglifier!
    – joshp
    Commented Jan 21, 2016 at 5:03
  • Thankfully, when V8 came out, the designers decided that they wouldn't play the artificial microbenchmarks game any more and created benchmarks that simulate real-world, well-factored, well-designed, idiomatic code, and the other vendors now followed suit. This resulted in a role reversal in the performance game: before it was the job of the programmer to write his code for performance so that the compiler writers have an easy job, now it's the job of the compiler writers to design their compilers for performance, so that the programmer has an easy job – which is the way it should be. Commented Jan 21, 2016 at 10:53
  • Nice red herring, but spoken languages share a geographic limit, computer languages do not. So your point is a little moot. Not to mention comparing Python vs JavaScript with Parisian vs Montreal dialects. (I'm not sure who would take more offense, Python Programmers or Montreal inhabitants? ;D ).
    – Marco
    Commented Jan 26, 2016 at 23:32

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.


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.

  • I wish I could give another +1 for that FizzBuzzEnterpriseEdition link alone... :-D Commented Jan 21, 2016 at 17:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.