TITLE: Does Readability Give a False Sense of Understandability?
AUTHOR: Eugene Wallingford
DATE: March 11, 2013  4:25 PM
DESC: 
-----
BODY:
In
<A HREF="http://www.storytotell.org/essays/good-for-whom.html">
   Good for Whom?</A>,
Daniel Lyons writes about the readability of code.  He starts
with Dan Ingall's classic
<A HREF="http://www.cs.virginia.edu/~evans/cs655/readings/smalltalk.html">
   Design Principles Behind Smalltalk</A>,
which places a high value on a system being comprehensible
by a single person, and then riffs on readability in J and
Smalltalk.

Early on, Lyons made me smile when he noted that, while J
is object-oriented, it's not likely to be used that way by
many people:

<BLOCKQUOTE><EM>
... [because] to use advanced features of J one must first
use J, and there isn't a lot of that going on either.
</EM></BLOCKQUOTE>

As a former Smalltalker, I know how he feels.

Ultimately, Lyons is skeptical about claims that readability
increases the chances that a language will attract a large
audience.  For one thing, there are too many counterexamples
in both directions.  Languages like C, which "combines the
power of assembly language with the readability of assembly
language" [
<A HREF="http://www.cs.uni.edu/~wallingf/blog/archives/monthly/2007-02.html#e2007-02-23T19_58_32.htm">
  link</A>
], are often widely used.  Languages such as Smalltalk, Self,
and Lisp, which put a premium on features such as
<A HREF="http://www.cs.uni.edu/~wallingf/blog/archives/monthly/2006-03.html#e2006-03-07T18_44_26.htm">
   purity</A>
and
<A HREF="http://www.cs.uni.edu/~wallingf/blog/archives/monthly/2004-10.html#e2004-10-22T16_23_37.htm">
   factorability</A>,
which in turn enhance readability, never seem to grow beyond
a niche audience.

Lyons's insight is that <B>readability can mislead</B>.  He
uses as an example the source code of the J compiler, which
is written in C but in a style mimicking J itself:

<BLOCKQUOTE><EM>
So looking at the J source code, it's easy for me to hold my
nose and say, that's totally unreadable garbage; how can that
be maintained?  But at the same time, it's not my place to
maintain it.  Imagine if it were written in the most clean,
beautiful C code possible.  I might be able to dupe myself
into thinking I could maintain it, but <B>it would be a
lie</B>!  Is it so bad that complex projects like J have
complex code?  If it were a complex Java program instead, I'd
still need substantial time to learn it before I would stand
a chance at modifying it.  Making it J-like means I am required
to understand J to change the source code.  <B>Wouldn't I have
to understand J to change it anyway</B>?
</EM></BLOCKQUOTE>

There is no point in misleading readers who have trouble
understanding J-like code into thinking they understand the
compiler, because they don't.  A veneer of readability cannot
change that.

I know how Lyons feels.  I sometimes felt the same way as I
learned Smalltalk by studying the Smalltalk system itself.  I
understood how things worked locally, within a method and then
within a class, but I didn't the full network of classes that
made up the system.  And I had the scars -- and trashed images
-- to prove it.  Fortunately, Smalltalk was able to teach me
many things, including
<A HREF="http://www.cs.uni.edu/~wallingf/blog/archives/monthly/2011-09.html#e2011-09-08T20_19_25.htm">
   object-oriented programming</A>,
along the way.  Eventually I came to understand better, if
not perfectly, how Smalltalk worked down its guts, but that
took a lot of time and work.  Smalltalk's readability made the
code accessible to me early, but understanding still took time.

Lyons's article brought to mind another insight about code's
understandability that I blogged about many years ago in
<A HREF="http://www.cs.uni.edu/~wallingf/blog/archives/monthly/2004-09.html#e2004-09-22T14_24_40.htm">
   an entry on comments in code</A>.
This insight came from Brian Marick, himself no stranger to
Lisp or Smalltalk:

<BLOCKQUOTE><EM>
[C]ode can only ever be self-explanatory <B>with respect
to an expected reader</B>.
</EM></BLOCKQUOTE>

Sometimes, perhaps it's just as well that a language or a
program not pretend to be more understandable than it really
is.  Maybe a barrier to entry is good, by keeping readers
out until they are ready to wield the power it affords.

If nothing else, Lyons's stance can be useful as a
counterweight to an almost unthinking admiration of readable
syntax and programming style.
-----