To Write Readable Code Know Your Audience

I like clean and easy to understand code. 

Like most programmers, I have encountered code that (to me) appears clean, elegant and easy to understand. And I have encountered code that is too clever for it's own good. 

I have personally written code that, at the time I wrote it, seemed clever and clear. Then, six months later, I couldn't figure out what I had written. It's not good when you can't figure out your own code.

But here is the interesting thing. I have been writing and teaching code for years. And one thing I have observed over and over again is that not every one agrees on what is clean, elegant and easy to understand. What's more, my idea of what is clean, elegant and easy to understand evolves over time.

Let me give you 3 examples of things that, at one point in my career, made code far less readable. And now, at least to me, make my code more readable than alternative techniques that do the same thing.

1. Callbacks. I still remember the first time I attempted to use a callback. It was forced on me by the tool I was using. It was needed to customize a Microsoft Access combo box. And your average Microsoft Access developer was not, in general, required to know about callbacks. The callback concept completely blew my mind. Very counter intuitive. 

Needless to say, I now use callbacks all the time, and consider them, when used appropriately, to be a valuable part of good, clean code.

Also, in retrospect, I realize that, as an Access programmer, I was already using callbacks unknowingly. That is because an event handler, like button1_onClick, is really just a type of callback.

2. Recursion. The first time I saw recursion, it was hard to understand and unintuitive. I tried to avoid it at all cost. Many of the things that can be done with recursion can be done using other techniques. But after having written 1000s of lines of code dealing with graph and tree structures, I now know that for many things, recursion is simply the most simple and elegant solution.

3. Functional Programming with Lambdas. Take a look at this chunk of JavaScript:

return 
  products
    .filter((p) => p.price < 100)
    .map( (p) => p.title )
    .sort();

There was a time in my career, when I would avoid this style of code like the plague. If I came across code like this, I would rewrite it in a more imperative way, just so I could comprehend it. 

Fast forward a few years, and, as you may have guessed, I now find this chunk of code to be perfectly elegant, concise and easy to understand. 

Know You Audience.
So here is the point: if you are writing code and you expect your code to be readable by others, you have to know your audience. 

My guess is that the average Google or Facebook programmer will be perfectly comfortable reading code that makes liberal use of callbacks, recursion and functional code style. Also, I am sure that if you checked out some random samples of recent code written by Google or Facebook, you would find these things.

On the other hand, a few years ago I had written an app for the state of California. This app was to be eventually maintained by a group of government programmers, who all come from a background that did not make use of things like recursion, callbacks or functional programming. So I explicitly tried to write my code in a way that they would understand.

So here is a question: should you dumb down your code to make it more readable to less experienced programmers? Or should you expect other developers to step up their game and figure it out?