Re: [tlug] Code Readability (was: perl?)

[Benjamin Kowarsch <trijezdci@example.com>]

Hi Curt,

On 19 August 2016 at 22:24, Curt Sampson <cjs@example.com> wrote:

A lot of people think about readability as a property of a language,

And in the majority of cases they would be right to think so, but probably for a different reason than they think.
 

but that's not right. The language certainly has an influence (mainly
by its limitations) on potential readability, but what decides whether
something is readable or not is the other people reading it, and in
particular the background they have with that code base.

What decides readability is mental load.
 

My favourite example to start with for these things is to look at a
notation that is at once familiar and frightening to people:

Your favourite example is rather naive and you are making the mistake to equal brevity with readability and verbosity with diminished readability when in reality it could go either way.

A better example would be typical run of the mill multi-modal notations out in the wild, such as Perl regular _expression_ syntax and its many many many derivatives, each one messing about with the set of modifier symbols and switches to turn them on and off in specific contexts.

With all this multi-modality, you can no longer tell for a given arbitrary context whether something like \( means a verbatim opening parenthesis or an opening group modifier symbol. It could be either depending on multi-modal settings and context. Within the context of brackets, it could again mean something different, etc etc.

Brevity or not, multi-modal notations are always bad. They greatly increase the opportunity for error, even for seasoned practitioners.

al-Khwārizmī:

    You divide ten into two parts: multiply the one by itself; it will
    be equal to the other taken eighty-one times.

vs

    (10 - x)² = 81x

Which one is easier to read?

But now imagine that the ^2 could mean either squared or factorial or some other operation, depending on some definition on a different page at the end of the current chapter in which the formula is presented. Then imagine that more than half the symbols in the formula would be like that, that they too could have different meanings depending on something that is not actually part of the formula. And in a different book, it could mean something  different yet again. No two formulas in two different books would mean the same, even if they look the same.

If mathematical notation worked like that, we would still be in the medieval ages and Al Chwarizmis plain text version would then be more readable. Not because it is plain text but because it is not multi-modal.

Luckily, mathematical notation is near free of multi-modality and in the rare occasions where it is, mathematicians are usually aware of the ambiguity and provide a note for clarification right before they present their formula.

One example, set difference is primarily denoted by a reverse solidus A \ B, but sometimes a minus is used A - B which is ambiguous as the latter could mean the set of the differences of elements. For this reason ISO 80001 states that minus should never be used for set difference even if though it has been used in this way in the past. Luckily, such scenarios are rather rare in mathematics. Unfortunately, the same is not the case for a large part of programming notations.

This is what determines readability. Not the brevity of the notation or lack of it relative to plain English, but the consistency and uniformity and predictability of symbols.

IOW, mathematics beats natural language for complex expressions because of its consistency and well-definedness and predictability, not because of brevity.

A notation that has ambiguity as a "feature" is always less readable. The more ambiguity, the less readable. If there is a chance to interpret symbols in different ways and it requires cross reference checks to obtain meaning, that diminishes readability, regardless of brevity.

regards

benjamin