[tlug] Code Readability (was: perl?)

[Curt Sampson <cjs@example.com>]

On 2016-08-15 17:14 +0900 (Mon), Stephen J. Turnbull wrote:

> Josh Glover writes:
>  > One great way to keep codebases smaller is to use a more expressive
>  > language, such as Clojure, Haskell, Racket, OCaml, etc.
> 
> Or all of them!  (Hi, Curt!)  But that hurts readability, too, not all
> developers can be that multilingual, and sometimes you do need to read
> code that others maintain.

Oh, hi!

A lot of people think about readability as a property of a language,
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.

My favourite example to start with for these things is to look at a
notation that is at once familiar and frightening to people:
mathematics. Most people hate and fear mathematical notation, but
let's go back a thousand-odd years and look at an original problem
from al-Khwārizmī, the inventor of algebra:

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

He was writing this without the benefit of modern mathematical
notation.  So let's translate this into scary technical notation as
used by modern mathematicians which al-Khwārizmī wouldn't have
understood at all:

    (10 - x)² = 81x

Which one is easier to read?

In the programming world, COBOL of course provides wonderful examples
to modern programmers of how the definition of "easy to read" can
change. At the statement level you can get a brief taste:

    COBOL:		ADD 1 TO X GIVING Y
    anything else:	y = x + 1

but a full program really brings out the concept:

    IDENTIFICATION DIVISION.
    PROGRAM-ID. HELLO.

    DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 WS-NAME PIC X(25).

    PROCEDURE DIVISION.
       ACCEPT WS-NAME.
       DISPLAY "Hello, " WS-NAME.

    STOP RUN.

Looking just at modern languages, yes, Haskell for example has
brilliantly concise syntax that can take a bit of getting used to. But
even in Ruby alone we have different levels of verbosity that, will
each be easier or harder to read, depending on where you come from.

In code that might have to be maintained by random people of varying
talents and skill levels who don't program much, and certainly rarely
touch your project, you might well be advised to write:

    def double_each_number_in_array(array_of_numbers)
	array_of_doubles = []
	for number in array_of_numbers
	    array_of_doubles.append(number * 2)
	end
	return array_of_doubles
    end

But only if you're not touching it a lot. If you're working with
"regular" Ruby programmers, you'll certainly find this much better:

    def double_array(numbers)
	numbers.map do |n|
	    n * 2
	end
    end

Personally, I find even that very tedious, with then (admittedly rather
mathematical) conventions within which I work, and would write:

    def double(xs); xs.map { |x| x*2 }; end

I read this third example easily two or three times as fast as the
second example, and I also end up with an extra four lines of other
code in my terminal letting me scroll less. But most Ruby programmers,
even the good ones, would disagree with me; they don't accept a few
of my conventions and ideas used here:

1. If you have just a generic number in a small context, call it `x`.
2. A list of things is the name of the thing with an `s` on the end.
3. Put short stuff on a single line.
4. Don't use extra characters and extra lines for do/end when you
   can use the shorter braces {} that also let you do paren matching

Points 1 and 2 are conventions you learn, get used to, and they become
nice concise ways of saying something that everybody understands.

Point 3 lets you see more code on the screen, and live with mere
80 and 90 line terminals.

Point 4 is usually where I get the strongest pushback amongst Ruby
programmers (especially Rails ones), and I have no idea why. I expect
that's the same thing that keeps making people make new and even good
languages (such as Rust) and then cripple them with an "it must use C
syntax" principle.

Another example of something you never want to retreat from once
you get used to it is dropping syntactic "if" for more concise
boolean expressions. I use shell here as an example, but it applies
equally to (and I do the same in) Ruby:

    if ! tty -s; then
	echo 2>&1 "You must be on a terminal."
	exit 1
    fi

versus

    tty -s || { echo 2>&1 "You must be on a terminal."; exit 1; }

The long and short of it is:

First, write for your audience. Programmers spend most of their time
reading code, and so you need to optimize your style for the people
who read it most. This style will change over time as you work
together.

Second, try to work with your group to optimize your style. A good
place to start is to read Edwart Tufte's classic book _The Visual
Display of Quantitative Information_[1]. It's not always obvious how
to apply his principles to code, but his ideas are absolutely sound.

[1]: https://www.edwardtufte.com/tufte/books_vdqi

cjs
-- 
Curt Sampson         <cjs@example.com>         +81 90 7737 2974

To iterate is human, to recurse divine.
    - L Peter Deutsch