

Readability can mislead - ColinWright
http://www.cs.uni.edu/~wallingf/blog/archives/monthly/2013-03.html#e2013-03-11T16_25_31.htm

======
comex
Wow. The code mentioned (J compiler source) has to be seen to be believed.
Here is a snippet:

    
    
        static F1(jtthn){A d,t,z;C*tv,*x,*y,*zv;I c,*dv,k,m,n,p,r,*s,wd;VF fmt;
         n=AN(w); r=AR(w); s=AS(w);
         thcase(AT(w),&wd,&fmt);
         GA(t,LIT,wd*(1+n),1,0); tv=CAV(t);
         if(1>=r){p=thv(w,AN(t),tv); ASSERTSYS(p,"thn"); AN(t)=*AS(t)=p; z=t;} 
         else{ 
          c=s[r-1]; m=n/c; k=bp(AT(w));
          y=tv-wd; x=CAV(w)-k; 
    

The function is in a file conveniently called "f.c", and I cannot find any
explanation for the abbreviation "jtthn" nearby. It seems to be a prefix to
"thn". "thn" does not appear to be defined anywhere in the J documentation.
Maybe it's a combination of letters that would make sense to a J expert?

Now, if the reason for this is to save typing, fine. If it's the best way for
the people who are working on the compiler to work (no pesky time spent
writing comments), and they don't care whether anyone else understands, fine.
I don't think that code authors have any particular responsibility to make
their work understandable or modifiable by others, if they don't want to.

But the idea that this provides a reasonable barrier to entry, as suggested in
the article, that learning how the code works is a reasonable rite of
initiation because only the initiated need bother modifying the code, is
simply arrogant. Yes, once code gets very verbose, adding further verbosity
and explanation is putting lipstick on a pig - it won't help someone who
doesn't understand understand, and it's no use to someone who does. But this
code is nowhere near that point, I suspect even for someone who knows J. I am
capable of understanding how a compiler works, but if I were ever called upon
to debug this one, the code would make me waste my time understanding its
idiosyncrasies before I could get to the meat of things.

The format is at best a necessary (useful?) evil, not something to celebrate.
A few longer names or comments would go a long way.

~~~
lokedhs
That looks like typical code written by a mathematician. Look online for
implementations of various mathematical algorithms and you'll get more code
like this than you'll ever wanted to ever see.

~~~
comex
That's an interesting thing to say, because from my unskilled perspective, a
set of equations in a math paper really does often require enough background
knowledge and deep understanding that there's not much point giving variables
long names - you'll have to study it for a while anyway. Code is not like
that; it's fluffier, and can usually be understood on a first read (and
there's more of it), so long names are useful.

But maybe I'm just saying that because I'm better at code than mathematics?

~~~
lokedhs
I think it has more to with mathematicians seeing programming as nothing more
than an implementation detail. They spend their time designing an algorithm on
paper, writing a paper on it and probably has a whole pile of versions sitting
on his desk. They see no value in the program itself and thus they simply
translate the formulas to source workout any thought of it being maintainable
or even understandable.

That said, I do remember seeing mathematicians calling for a better math
notation that emphasises readability and longer variable names. I'm not so
sure it'll happen though. I prefer to simply avoid having them write code
others have to maintain.

~~~
michaelfeathers
I think there is a lot more to this. Yes, better naming can help at times but
when a mathematician is looking at math they are seeing structure. It is a
different mode of perception than reading a program as a narrative.

It's not better or worse, it's just different.

------
Chris_Newton
One difficulty with these discussions it that there is no standard, objective
definition of readability. Without one, it’s hard to debate statements like
the title of this thread, “Readability can mislead”.

After thinking about this a lot, I settled on a personal definition of “ease
of extracting useful information from the code”. This recognises some
principles I’ve found to be important when discussing readability and how to
improve it. For example, different knowledge will be useful depending on what
you’re trying to achieve and what you already know, so code may be more
readable for some purposes than others. Similarly, information may be
relatively easy to extract for someone with one background or set of tools but
harder for someone else to obtain under different circumstances. This means
readability is always a balancing act, and something that makes code more
readable for one purpose or reader may actually harm the readability in
another context.

This explains a lot of subjective preferences based on the reader’s
background. For example, in the _Good for Whom?_ article by Daniel Lyons[1]
that was cited by the article we’re discussing, there is a question of whether
a one-line regular expression does anything to aid readability, and whether a
much more verbose Smalltalk-style implementation of the same logic is more
readable. I believe the most important thing to recognise in that debate is
that the readability of the regex version is dramatically different depending
on whether the reader understands regex syntax. If so, it is probably much
easier to read than the long form version, but if not, it's just executable
line noise. Therefore whether it is helpful to employ a regex for that task
depends a lot on who you expect to be reading the code later and what
assumptions you are willing to make about their skills and knowledge. A
similar dilemma is almost inevitable when choosing almost any significant
coding standard.

[1] <http://www.storytotell.org/essays/good-for-whom.html>

~~~
cafard
I think that Marick's comment in the article expresses this well.

------
bithive123
> Lyons is skeptical about claims that readability increases the chances that
> a language will attract a large audience.

The article makes an important point but I've always interpreted readability
in terms of expressiveness: To what (admittedly qualitative) extent does the
language help a fluent developer write readable code (where each line flows
naturally from the next)?

Rather than attracting people to the language, it's about hitting that sweet
spot where the code is highly "compressed" yet still has a natural syntax
without being opaque. I find that the syntactic overhead imposed by some
languages (i.e. those that don't require indentation or which lack array
literals, for instance) has less of an effect on readability than the author's
skill. PHP has these flaws but can still be quite readable, and in that sense
readability should be attractive.

~~~
Evbn
Which language has "natural syntax"? Answer: the one with the most similar
syntax to the one you know best.

~~~
ritchiea
Maybe it's because I was introduced to both Ruby and Python early on in my
career but I disagree. There are languages that encourage writing semantic
code and thus making readability a function of how close the code is to an
english description of how to implement the task at hand.

~~~
Gormo
So, because you're most familiar with English syntax, the most readable
programming languages are the ones which most closely approximate it? Doesn't
sound like a disagreement with Evbn's point.

~~~
ritchiea
Do you use any programming languages that don't use English syntax?

~~~
Gormo
I don't use any programming languages that _do_ use English syntax - I'm not
even aware of any such programming languages - and I don't really understand
the position that the optimal language for issuing instructions to a computer
is the one that looks most like a language meant to facilitate dialogue among
human beings.

