4 ms·
Readability can mislead
- comex 14y agoWow. 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 14y agoThat 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 14y agoThat'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 14y agoI 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 14y agoI 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.
- Evbn 14y ago> they simply translate the formulas to source workout any thought of it being maintainable or even understandable. Or correctness, sadly.
- icelancer 14y agoThe code I write that is heavily math-based tends to look like this, I will sadly admit.
- breadbox 14y agoOh crap. At first I thought that was an example of J source code. It wasn't until I read the article and came back that I realized it was pure C.
- michaelfeathers 14y agoI think that this is an interesting example. Can I read this code? No. But, I can't read Czech or Finnish either. The person who wrote this C code relied upon idioms that they either developed themselves or are part of a culture around J. I think that with that context we would understand it. The real question is whether there is enough discipline and regularity in the structure and idioms for someone to pick them up quickly. To me, that is the ultimate measure of comprehensibility. There are plenty of codebases with good naming that remain incomprehensible because they randomly violate the reader's expectations. I really think that internal consistency around a small number of concepts is ultimately more important to ease of learning than anything else. Look at this C code as a DSL, but one that you just don't have a crib sheet for. And, yes, that is a problem but it is definitely not the worst problem you can have.
- vadiml 14y agoIt seems to be translation from J (APL) to C...
- bithive123 14y ago> 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 14y agoWhich language has "natural syntax"? Answer: the one with the most similar syntax to the one you know best.
- ritchiea 14y agoMaybe 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.
- Chris_Newton 14y agoOne 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 http://www.storytotell.org/essays/good-for-whom.html
- cafard 14y agoI think that Marick's comment in the article expresses this well.