Does simplicity always improve Readability?

Question

Recently, I was developing a set of coding standards for our company. (We're a new team branching out into a new language for the company.)

On my first draft, I set the purpose of our coding standards as improving Readability, Maintainability, Reliability, and Performance. (I ignored writability, portability, cost, compatibility with previous standards, etc.)

One of my goals while writing this document was to push through the idea of simplicity of code. The idea was that there should be only one function call or operation per line. My hope was that this would increase readability. It's an idea that I carried over from our previous language.

However, I've questioned the assumption behind this push:

Does simplicity always improve readability?

Is there a case where writing simpler code decreases readability?

It should be obvious, but by "simpler", I don't mean "easier to write", but less stuff going on per line.

Answer 1

"Simple" is an overused word. "Readable" can profitably be defined as "simple to understand", in which case increasing (this measure of) simplicity by definition increases readability, but I don't think this is what you mean. I've written about this elsewhere, but generally something can be called "simpler" either by being more abstract (in which case fewer concepts can express more phenomena) or by being more concrete (in which case a concept does not require as much background knowledge to understand in the first place). I'm arguing that, depending on perspective, a more abstract concept can reasonably be called simpler than a more concrete concept, or vice versa. This, even though "abstract" and "concrete" are antonyms.

I'll use as an example some Haskell code I wrote a while ago. I asked a question on stackoverflow about using the List monad to calculate a counter in which each digit could have a different base. My eventual solution (not knowing much Haskell) looked like:

count :: [Integer] -> [[Integer]]
count [] = [[]]
count (x:xs) =
  -- get all possible sequences for the remaining digits
  let
    remDigits :: [[Integer]]
    remDigits = count xs
  in
  -- pull out a possible sequence for the remaining digits
  do nextDigits <- remDigits
     -- pull out all possible values for the current digit
     y <- [0..x]
     -- record that "current digit" : "remaining digits" is
     -- a valid output.
     return (y:nextDigits)

One of the answers reduced this to:

count = mapM (enumFromTo 0)

Which of these is "simpler" to understand (i.e. more readable) depends entirely on how comfortable the reader has become with (abstract) monadic operations (and, for that matter, point-free code). A reader who's very comfortable with these abstract concepts will prefer to read the (short) more abstract version, while one who is not comfortable with those operations will prefer to read the (long) more concrete version. There is no one answer about which version is more readable that will hold for everybody.

Answer 2

One function call per line is simpler? Let's try an example!

=== One call per line ===
x = y.getThis()
a = x.getThat()
b = a.getSomethingElse()

=== Less "simple" version ===
b = y.getThis().getThat().getSomethingElse()

What do you think? Is one call per line actually simpler?

Answer 3

You're all missing some fundamental definitions. Simple, from the root sim-plex, means one fold. Simple means doing one thing. Easy, from the root ease, means lie near. Easy means that it is close at hand. The examples of simple code given in other answers aren't exactly what they appear.

Take rotsor's display of a very large value. He says this is simple. Is not, in my estimation, simple. It's easy. It's close at hand to type the number of required 0s.

10000000000000000000000000000000000000000000

The readable version is simple. It does one thing. It expresses the number by describing its size in a notation purpose built for this function.

1e43

Could you describe Aidan's "simple" code snippet as doing one thing? It contains 10 lines of code (not counting comments) and at least 7 blocks (as I'd count them). If you follow the comments, you'd see that it does at least 4 things!

count :: [Integer] -> [[Integer]]
count [] = [[]]
count (x:xs) =
  -- get all possible sequences for the remaining digits
  let
    remDigits :: [[Integer]]
    remDigits = count xs
  in
  -- pull out a possible sequence for the remaining digits
  do nextDigits <- remDigits
     -- pull out all possible values for the current digit
     y <- [0..x]
     -- record that "current digit" : "remaining digits" is
     -- a valid output.
     return (y:nextDigits)

But, one of the recommendations for rewriting this code was one statement. Aidan does state that a reader would have to be or become familiar with monadic statements, pointer free code, etc. That's fine. Those concepts are singular and independent to learn.

count = mapM (enumFromTo 0)

You'll find that truly simple code is more readable than easy code because it does only one thing. You may need to go off and learn more "one things" to understand the simple code. But it should always be more readable.

Answer 4

If I go for simplicity, I can write code like this:

10000000000000000000000000000000000000000000

But if I go for readability, I will prefer this:

1e43

On the other hand, 1000 is much more readable and simple than 1e3 unless you work with numbers in scientific notation all the time.

This is a degenerate example of much more general pattern you can find almost anywhere -- building something out of very simple blocks can quickly become unreadable/inefficient/bad in a lot of different ways. Generalizing and reusing, on the other hand, is harder at first ("wtf is e?! did they mean to write 1343?" someone might say), but can help a lot in the long run.

Answer 5

The questions reminds me of this answer on Stack Overflow, particularly this quote (substitute quality with simplicity):

Quality -- you know what it is, yet you don't know what it is. But that's self- contradictory. But some things are better than others, that is, they have more quality. But when you try to say what the quality is, apart from the things that have it, it all goes poof! There's nothing to talk about. But if you can't say what Quality is, how do you know what it is, or how do you know that it even exists? If no one knows what it is, then for all practical purposes it doesn't exist at all. But for all practical purposes it really does exist. What else are the grades based on? Why else would people pay fortunes for some things and throw others in the trash pile? Obviously some things are better than others -- but what's the ``betterness''? -- So round and round you go, spinning mental wheels and nowhere finding anyplace to get traction. What the hell is Quality? What is it?

I think that it's important that you keep in mind that a codified coding standard for all its benefits will not make good programmers out of bad ones. A word like 'simple' may be interpreted differently by different people (see Aidan Cully's answer), but that may not be such a bad thing. Junior programmers will still need to have their code reviewed by senior programmers and learn why the senior programmers interpretation of 'simple' is better than their own.

Answer 6

Readability and simplicity are subjective terms which, depending on the person and the context, usually but not always go together.

A more objective term is conciseness - something you could in principle count by counting characters, though there are some flaws in that. Conciseness seems to imply simplicity and readability, but there are (at least in my opinion) exceptions.

A longer (and arguably more complex) piece of code can be more readable if it better expresses intent. Whether your definition of simplicity cares about intent is another subjective thing - you could define complexity in terms of the syntactic structure and information-theory entropy, for instance, with no reference to intentions at all.

So, a well-chosen longer variable name may...

• Improve readability by better expressing intent
• Reduce conciseness - it is longer, after all
• Have no effect on syntactic simplicity at all - the syntactic structure of the code is unchanged

Similarly, I might write if (some_boolean == true). In comparison with the equivalent alternative if (some_boolean), this...

• Reduces conciseness
• Reduces syntactic simplicity, but
• May improve readability by better expressing intent.

Of course this one will trigger a mass protest - to plenty of people, this always damages readability too. To me, it depends a lot on the source of the boolean - e.g. the variable name (or method name or whatever) may not clearly express that the value is "truth value". Sure, the if tells you something, but it still smells. But plenty of people will call me an idiot for believing this.

Which is further evidence of the overall subjectivity, of course.

Answer 7

Does simplicity always improve readability? Yes. Is one statement per line always simpler? No. Quite a few languages have a ternary operator, which, once grasped, is simpler and easier to understand than the equivalent if/else assignments.

In languages that allow multiple variables to be set on one line, doing so is frequently simpler and easir to understand than whatever the equivalent is.

Another example: regular expressions do a lot, typically in just one line, and the equivalent without a regex is frequently much harder to read. /\d{3}[ -]\d{3}-\d{4}/ is the equivalent of a function call with several comments at the least, and is easier to understand than the corresponding function body.

Answer 8

Clarity + Standards + Code Re-use + Good Comments + Good Design could improve readability.

Simplicity is not always in the hand of the developer because the nature of algorithms and the complexity of application structure these days.

Take the simple web pages that perform simple tasks. Given a sort routine, it is not possible to simplify the logic, but you can make it clearer with comments, using meaningful variable names, having it written in a structured manner, etc.

Answer 9

Always? - YES

Attaining the right level of simplicity is a complex and difficult undertaking. But always worthwhile since it always improves readability. I think the key is deep understanding. Simplicity is an absolute, measured by "new concepts" per "chunk" of code. A few new concepts means simpler.

Focus on areas where there are a dense cluster of concepts and find ways to "chunk" or "summarize" or "abstract". Make a couple of passes through the code to make it simpler and more readable.

A good abstraction is worth it's weight in gold. A good abstraction makes this simpler -- and consequently more readable.

Answer 10

Less "stuff per line", simplicity, and readability are not the same thing. One can take an incredibly complicated obscure undocumented algorithm and code it with 1 statement per line instead of 2, and it won't become that much more readable.

Less "stuff per line" also might require supplying developers with great big tall monitors to see code blocks now spread out more vertically. Or cause eye strain from reading tinier fonts.

Readability is it's very own metric, which often requires a compromise among several other more easily measurable metrics. Pre-constrain all those other metrics, and the compromise no longer becomes possible, resulting in less readable code.

Answer 11

Does simplicity always improve readability?

No. I have seen plenty of cases where doing multiple simpler things on one line is less complex than having multiple lines.

There is a trade off between less code and simpler code.

In general I would recommend going for simpler code unless your sure doing it in fewer lines is better. I would much rather "too verbose" code over "too complex"

Answer 12

"Make things as simple as possible, but no simpler" - An often paraphrase of Albert Einstein

Simplicity improves everything. For differing values of simplicity, of course. Is it less lines of code? Maybe. Is it a smaller executable? Possibly. Is it something your team needs to agree upon? Absolutely.

Answer 13

If your coding standard is about "Readability, Maintainability, Reliability, and Performance" then just state that.

Don't try and prescribe how to achieve these things as there will always be situations where there is a counter example.

What you do need to prescribe is things that will cause code to break if not adhered too. Stylistic traits will not break code and should be suggestions (as long as a majority of the team agree that it is Readability the rest should be developer preference (with code review so that peer pressure reminds people that other people need to read the code)).

Answer 14

Always? - NO

Ironically, attaining the right level of simplicity can be a complex undertaking. I think the key is in moderation. Simplicity can also be in the eye of the beholder, so if you find yourself over-thinking it - just leave it alone or come back to it later.

Personally, when I try to go back and simplify something that I've written I focus on areas where I changed my mind or tried a couple of things to get what I wanted. Those areas can usually be smoothed out. Then just make a couple of passes through the code to make it more readable without spreading things out so much that you're jumping all over the place to figure out what's happening on a debug.

Answer 15

Not necessarily. If you've got a complex operation, that complexity has to go somewhere. Reducing the number of "stuff" that goes on one line just means it will take up more lines, which can actually be detrimental to code readability if it makes your routine too "tall" to fit on one screen.