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

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 3

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 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

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 6

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.

Answer 7

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 8

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 tradeoff between less code and simpler code.

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

Answer 9

"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 10

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 11

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 12

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 13

Does simplicity always improve readability?

I would say, maybe with a little bit of controversy, absolutely not.

You could hand me a class with 200 member functions in its public interface, and it may be the most humanly-readable public interface out there. It might be a joy just casually reading through such code and its documentation. However, I wouldn't call it "simple", because in spite of the readability, I would have to be concerned with how all these functions interact with each other, and potentially watch out for tricky edge cases resulting from misuse.

I would prefer a class with 20 member functions that weren't so easy to read to 200 that are, because "readability" is not the top priority to me in terms of preventing human error and improving the maintainability of code (the ease at which we can change it, i.e.).

However, this is all going to hinge on our personal definition of "simplicity". "Readability" typically doesn't vary that wildly among us, unless someone has acquired so much expertise and fluency that they consider regex to be very "readable", e.g., forgetting the rest of us mere mortals.

Simplicity

There was a time, long ago, where I thought "simplicty" meant "as easy to read as possible". So I would write C code with a lot of convenience functions, trying to improve the syntax and make things as easy to read and write as possible.

I designed very big, rich, high-level libraries as a result, trying to model a function for every natural human thought: helpers upon helpers upon helpers, all to shape the client code to a more readable syntax. The code I wrote back then may have been the most "readable", yet it was also the most "unmaintainable" and "complex".

Lisp

Yet I had a brief passion with LISP around the mid-90s (latecomer). It changed my whole idea of "simplicity".

LISP is not the most readable language. Hopefully no one thinks that extracting CDRs and CARs while invoking a recursive function with a boatload of nested parentheses is very "readable".

Nevertheless, after struggling to get my brain wrapped around the language's odd syntax and totally recursive ways of doing things, it permanently changed my idea of simplicity.

What I found with the code I wrote in LISP is that I was no longer making subtle errors anymore, even though the trickiness of thinking that way had me making more blatant mistakes (but those are easy to spot and correct). I wasn't misunderstanding what a function was doing and missing out on a subtle, unanticipated side effect. I was just having an easier time in general making changes and writing correct programs.

After LISP, simplicity to me became about minimalism, symmetry, flexibility, fewer side effects, fewer but more flexible functions that combine together in an infinite variety of ways.

I came to appreciate the mindset that the most reliable code of all is code that doesn't exist. While it's only a crude metric, I tend to see the potential for unreliability of code based on its quantity. Seeking the utmost syntactical convenience and readability tends to increase that quantity by a large factor.

Minimalism

With the LISP mindset embedded in me, I came to prefer minimalist APIs. I'd prefer a library with fewer but more reliable, flexible functions that are less convenient and potentiality harder to read than one which offers a boatload of "convenient" helpers and such which may make the code easy to "read" but potentially trip over more issues with unreliability and surprises that result from misunderstanding what one of these thousands of functions do.

Safety

Another thing about LISP was safety. It promoted minimal side effects and pure functions, and that was where I no longer saw myself making subtle mistakes, even though the difficulty of reading and writing in the language increased more blatant mistakes I could spot 10 seconds later.

Pure functions and immutable states became preferable to me whenever I could afford it, even if the syntax of:

sword = sharpen(sword)

... is a little less straightforward and detached from human thinking than:

sharpen(sword)

Readability VS. Simplicity

Yet again, LISP is not the most "readable" language. It can pack a lot of logic into a small section of code (possibly more than one human thought per line). I tend to ideally prefer one human thought per line for "readability", but it's not necessarily for "simplicity".

With this kind of definition of "simple", sometimes "simple" might actually somewhat compete with "readable". This is considering things more from an interface design point of view.

A simple interface means you need to learn far fewer things to use it, and potentially has greater reliability and fewer gotchas as result of its minimalism. A comprehensive documentation on the subject might fit a booklet rather than a massive volume of books. Nevertheless, it might require some more grunt-work and yield less readable code.

"Simple" to me improves our ability to understand the functionality in our system at a broad level. "Readable" to me improves our ability to connect each little line of code to natural language and thought and might speed up our understanding of what one line of code does, especially if we're not fluent in the language.

Regex is an example of what I consider "extremely simple". It's "too simple and too unreadable" for my personal taste. There's a balancing act for me between these extremes, yet regex does have that LISP-like quality of simplicity as I define it: minimalism, symmetry, incredible flexibility, reliability, etc. The problem for me with regex is that it's so simple that it has become so unreadable to the point where I don't think I'll ever become fluent at it (my brain just doesn't work that way and I envy people who can write regex code fluently).

So anyway, that's my definition of "simplicity", and it is completely independent of "readability" and may sometimes even interfere with the other, leading to a balancing act between a more "syntactically convenient" and readable but bigger library or a "syntactically inconvenient", less readable, yet smaller library. I've always found the true "convenience of understanding" and true "maintainability" priorities to align with the latter, with the strong preference towards minimalism even at some cost to readability and more natural human syntax (but not to the point of regex). YMMV.

Answer 14

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 15

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 16

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?