Clear is better than clever [pdf]

Compilers are very good at doing the ternaries for you. With good ol' Javascript you get things like the Google Closure Compiler that will return yet more Javascript rather than some bytecode, this informs me that my use of ternaries is a waste of time. I might as well go for the if/then/else type of approach and refactor it when it gets ugly into some functions.

My excuse for taking this approach in all languages is accessibility, with accessibility applying to people who can't really code. Whatever the language you can hack a few if statements even if you don't know the language. There are people who are learning and you want to make it 'accessible' for them.

Let the compiler do the work and stay off the bleeding edge features. That includes spaceship operators in PHP. I also think it is worth keeping code a few versions old, so in the case of the spaceship operator, I can do if/then/else things for the compiler to do the work and have my code work on someone else's box that is still on PHP 5.4 because the main software they use doesn't work on PHP 7.3.

Or in Javascript, it is obviously best practice to use the fancy new things but if your web page dies in the console on some Apple iPad running an old version of Safari then you can end up refactoring those best practice iterators into for loops. Invariably these refactoring exercises are hastily done, so you can come a cropper.

Another thing is that if I had to explain my code to someone then the nearer to natural language the better. The example ternary would require me to stop and think for a moment, if it was in boring if statements I could explain it to a not-so-technical person in terms they could understand, even if they could not write it themselves.

When you are talking about making code "clear," I think it's important to ask "clear about what?"

Is it:

* Clear about what the machine is doing?

* Clear about what the possible error cases are?

* Clear about the purpose of the code?

Go often prioritizes making it clear what the machine is doing over making the purpose of the code clear. In some languages you might write `newList = map(myFunc, myList)`. This is clear about what I intend, but not how it is accomplished[0]. The equivalent for-range loop in Go is clear about what it does at the expense of diluting the intent.

[0] for example, that map function could apply to the first element first, or the last element first, or it could apply to all the elements in parallel.

Short circuiting is poor for readability in my view because not only do you have to parse the syntax but you need to mentally walk through each case to understand what’s going on.

Traditional if/else conditionals express clarity by embedding the decision for myVar and visually show how it would be assigned in various cases.

As @hotBacteria said:

  if(cond1){
   myVar = 1;
  } else if(cond2 && cond3){
   myVar = 10;
  } else if(cond2 && !cond3){
   myVar = 100;
  } else {
   myVar = 4;
  }

  // Now return myVar
  return myVar;

I’ll take this syntax over short circuiting any day.

All IMO:

> However, I've never seen a convincing and objective description of clear code.

I take "clever code" to mean "code that looks pretty on surface the but requires the reader to dig in in order to understand the intent".

The problem with clever code is that it is misleading. It lacks empathy. You assume the next programmer will understand it at first glance just because it looks cool or pretty, but they'll struggle to parse it.

---

> Sometimes people mean that clear code is verbose code.

I also consider some verbose code to be "clever code" too. Most of the time it is just people using hammers where screwdrivers would be more appropriate:

- Unnecessary structures - eg: classes that could be functions taking 2x or 3x more space

- Unnecessary usage of polymorphism - eg: inheritance chain that could be a simple if

- Excessive indirection - eg: layered code where most of the time the layers don't do anything

- Plain wrong abstractions - eg: using query builders to build queries that would be smaller and more readable in SQL

- Fear of making classes too big - eg: instead of adding a method to a class, making a second class that knows too much about the innards of the first one

- Procedural code disguised as OOP - eg: breaking up a method into multiple private ones, but ending up having a lot of instance variables that were local variables before. When everything could be a single function.

---

> The best we have is cyclomatic complexity, but there's some reason to believe that line count may be a better indicator (which can't be good). And cyclomatic complexity completely misses the effect of mutable or immutable state, the presence of bad APIs, poor variable naming, etc.

Great observations. I agree 100%.

Since you mentioned it, I find cyclomatic complexity a bit too easy to game. I always wanted to have a metric that prevented people doing that, and took multiple methods into account.

When you break a method in three or four without adding REAL abstractions (a.k.a. "things you don't have to follow with the debugger to understand"), you're not making it easier to read, in fact you're making it harder because the reader has to jump around your code.

Of course, it's harder for machines to know the difference between good and bad abstractions. But I think we should take that into account in code reviews and such.