For me, the single most important element of style affecting readability is "consistency".

Whitespace

When I first encountered the long lamented Abigail-II's code on PM, it looked strange to my eyes. And despite that there are quite a few of his guidelines that I do not follow, and disagree with his reasoning, I always find his code eminently readable. Even when that code is performing the often complex manipulations for which he is famous, the consistency of his code layout makes spending time exploring his code a joy.

And of all the stylistic elements of his code that make that so, his liberal--too liberal in a few places for my tastes--and consistent use of horizontal whitespace ranks very high on the list of things that make it so readable. In large part, this is the inspiration behind my liberal use of horizontal whitespace. I attempted to code with consistency of layout long before I encountered Perl, but I've modified my coding style since using Perl to incorporate more horizontal whitespace and this has reflected back into my coding in other languages.

Tokens

As is demonstrated by this quote

Aoccdrnig to a rscheearch at an Elingsh uinervtisy, it deosn't mttaer in waht oredr the ltteers in a wrod are, the olny iprmoetnt tihng is that frist and lsat ltteer is at the rghit pclae. The rset can be a toatl mses and you can sitll raed it wouthit porbelm. Tihs is bcuseae we do not raed ervey lteter by it slef but the wrod as a wlohe.

from Txet Maglning Glof, Ayobndy?, we don't parse writing, including code, letter by letter, but rather, token by token. So ensuring that the tokens in our code are clearly delineated is (IMO), the greatest single contribution to readability.

Indentation

The second area where consistency also applies is in indentation. Whilst I hate the significant whitespace aspect of languages that use it--because it means that the entire function of a piece of code can silently change through the accidental omission or deletion of an invisible character. I hate inconsistent indentation even more. Why anyone would code this

PP(pp_padhv) {
    dSP; dTARGET;
    I32 gimme;

    XPUSHs(TARG);
    if( PL_op->op_private & OPpLVAL_INTRO ) {
        SAVECLEARSV( PAD_SVl( PL_op->op_targ ) );
    }
    if( PL_op->op_flags & OPf_REF ) {
        RETURN;
    else if( LVRET ) {
        if( GIMME == G_SCALAR ) {
            Perl_croak(aTHX_ "Can't return hash to lvalue scalar conte
+xt");
        }
        RETURN;
    }
    gimme = GIMME_V;
    if( gimme == G_ARRAY ) {
        RETURNOP( do_kv() );
    }
    else if( gimme == G_SCALAR ) {
        SV* const sv = Perl_hv_scalar( aTHX_ (HV*)TARG );
        SETs( sv );
    }
    RETURN;
}
[download]

like this,

PP(pp_padhv)
{
    dSP; dTARGET;
    I32 gimme;

    XPUSHs(TARG);
    if (PL_op->op_private & OPpLVAL_INTRO)
    SAVECLEARSV(PAD_SVl(PL_op->op_targ));
    if (PL_op->op_flags & OPf_REF)
    RETURN;
    else if (LVRET) {
    if (GIMME == G_SCALAR)
        Perl_croak(aTHX_ "Can't return hash to lvalue scalar context")
+;
    RETURN;
    }
    gimme = GIMME_V;
    if (gimme == G_ARRAY) {
    RETURNOP(do_kv());
    }
    else if (gimme == G_SCALAR) {
    SV* const sv = Perl_hv_scalar(aTHX_ (HV*)TARG);
    SETs(sv);
    }
    RETURN;
}
[download]

is so far beyond my understanding that it's not even worth my trying. I tried to think of an appropriate analogy here, but everything I came up with would have offended somebody.

Historical justifications

This is also why I eshew many of the common coding practices and style guidelines. Unlike Abigail's, most of them do not come with justifications other than historic precedence. If history was such a great recommendation, we'd still write English in the style of Chaucer!

Best practice changes over time. And sticking with ancient practices, "because that's how it's always been done", doesn't make sense. When I first started programming, squared coding sheets, manually assigned, widely spaced line numbers were derigour.

When I first wrote code commercially, 64x20(or 23?) green-on-black vdus were just starting to become available. So pouring (or is that pawing) over huge stacks of green&white fanfold listings with a handful of coloured highlighters was a necessary part of my daily life.

With the advent of bigger, color screens, and syntax highlighting editors, I find that I have rarely printed a piece of code out for the last 10 or more years.

Things moved on and so did I.

Justifictions

Where they do come with justifications, these are often (IMO) wrongly argued. For example, the justifiction for preferring underscore_separated_variable_names to camelCaseVariableNames is that the former makes it easier to parse the individual words--which it probably does to some degree. But this is a wrongly argued justification. The problem is that it makes visually separate tokens of those individual words, which you don't want. As demonstrated above, the human brain/eyes recognises patterns/tokens not characters and words, so breaking singular tokens into multiple, visually separate elements is a bad thing, not a good one.

By way of simplistic demonstration, how many parameters are there in the following?

some_function (some_variable,some_other_variable,and_yet_another_variable,and_one_more_for,luck)

someFunction( someVariable, someOtherVariable, andYetAnotherVariable, andOneMoreFor, luck )

Did you catch it the first time?

Huffman encoding

Another justifiction is that for Huffman encoding of keywords. Huffman encoding does make sense, but I've variously seen this justified on the basis of being quicker to type, or quicker to read, but these miss the point.

Coders do not type at 60 wpm. And if they do, they produce bad code. I remember a metric from a very long time ago that the average programmer codes around 10-12 lines of code per day. Of course, this isn't just the time it takes to type the lines, it reflects design, debugging, maintenance etc. over the life of the code. But even if you sit down to type in a piece of code, the function of which is clear in your mind and the algorithm for which is well known and a part of your mental lexicon, you still will rarely achieve anything approaching secretarial typing speeds. You will pause for some amount of time to decide what to name each variable. You'll pause to decide whether map or grep or for or redo is appropriate for this particular piece of iteration. Should you use print and interpolated variables or printf and a template?

Likewise, once you become familiar with keywords and function names, even those in code you just picked up, it will make negligible difference to your parsing speed whether the it is for or foreach, or map or applyThisBlockOfCodeToEachElementOfThisList. Once you know what the function/variable/keyword does, you will not parse the spelling of the token. You'll simply recognise it--the token, short or long--as doing whatever it does.

So that leaves us with the question, what is the real value of Huffman encoding? (IMO), it is twofold:

• Shorter is easier to remember--in context.

  My justifications for this are:

  • DANGER: KEEP OUT!

    Is more likely to have the desired affect than

    Within the area encircled by this metallic mesh barrier there exist localised high potential gradients that create the possibility for mis-endevour--including but not limited to burning, severe burning, maiming and termination of existence. You are accordingly advised that progressing inside the barrier could be hazardous.

  • We use acronyms in preference to their expansions--once we know what the acronym means.

    TIMTOWTDI!

    Of course, when you encounter an acronym or abbreviation for the first time, it doesn't make sense. But once you are familiar with them, and you are operating in the right context, not using them makes no sense. If you're a fan of Grey's Anatomy, ER or any of the many other medical soaps, then can you imagine the crash team screaming

    He's going into ventricular fibrillation, so would someone be so kind as to get me 30 cubic centiliters of D3, 1,25-dihydroxy-20-epi-Vitamin(*). Oh, and if it's not imposing upon you to much, could you do that as a matter of great priority please.

    Instead of

    He's going into v-fib, get me 30cc of epi, stat.

    *I have no idea if that's the correct expansion of "epi" in this context, but it lent itself to the point I am making and in truth, I don't need to know.

• Brevity == clarity.

  The more frequently something is used, the shorter it should be, because it takes up less screen space.

  That means that atomic elements of code can more often be coding in a single line. And that allows more discrete steps (preferably all of them), of an overall algorithm to be visible on a single screen. This is a huge, huge aid to understanding, both for the original author and the future maintenance programmer.

Long variable names

Another common (IMO mis-)perception is that long, descriptive variable names make for clearer code. This is only ever true for the first few minutes before you know what the variable is used for. After that, once you have internalised the purpose of a variable, they are just tokens. And, provided that their scope is suitably confined, the ability to recognise the token quickly and easily when scanning the code is inversely proportional to it's length.

Contrast

my @sorted = sort{ $a <=> $b } @names;
[download]

my @list_of_numerically_sorted_names = sort {
    $first_element_to_be_compared
    <=>
    $second_element to be compared
} @list_of_unsorted_names;
[download]

Of course, single character variable names are pretty useless if the life of the variable extends much beyond a few lines. But then most variables shouldn't have scopes that extend much beyond a few lines anyway--but that's a different discussion.

Whilst it is easy to argue that longer variable names allow the maintenance programmer (you, in a month or three's time), to quickly become familiar with the purpose of a variable when they first dive into a piece of code, (IMO) that is false economy. It (along with overly commented code), encourages a practice that I term 'hit & run' or 'guerrilla' maintenance. This is where the programmer receives a description of the problem, makes an assumption about the likely cause, dives into the middle of the code in question, reads a few comments or variable names and makes changes consistent with his earlier assumptions.

The problem is, descriptive variable names, like descriptive comments, describe what the original programmer thought they were coding. But the reason the maintenance programmer is in there, is because the code doesn't do what the original programmer thought it was doing. Of course, there are other reasons for maintenance than bugs, but I still feel that whenever you sit down to change a piece of code, you should understand what it does, and how it does it, not just what someone thought it should do, before you start making changes.

One of the ways I get to know a piece of code is to sit down and go through it changing the source-code layout to bring it to my preferred layout. I do this manually. I find that the process of inserting/adjusting whitespace, adjusting the indentation, and sometimes, even changing the variable names to fit my understanding of the code allows me to get a much clearer picture of the code at both the macro and micro levels.

Of course, this can offend some programmers and doesn't fit well with some source control and maintenance techniques, which means that once I have made my changes, I have to go back to the original sources and re-make them in the style of the original code if I intend to supply a patch for example. That could be seen as a problem, but it also serves as a secondary validation of the changes.

My take.

Vertical white space rules!

some_function (
    if_it_wasnt_for,
    bad_luck,
    I_wouldnt_have,
    any_luck_at_all,
) or die "handy place for your error msg\n";
[download]

Short names, long names, I don't care. Just make them meaningful. A few moments spent choosing a good name can save hours of misunderstanding (even your own) code later.

Code reuse is a good thing. I like variable name reuse too. :-)

While on the subject of consistency, one should avoid doing having code that does more extra work that is not directly related for why it was written. It should be like a conversation with parts of a conversation focusing upon the subject being discussed.

Example: BrowserUK wrote this, my wife bought a new car today and I hate my co-workers, excellent article and I enjoyed reading it.

This is a tough to read but is common problem among programmers.

A more practical example would be a function that mix SQL with business logic with HTML. Doing all three at the same time makes it hard to debug and reduces the portability of the code. You cannot,

• Use the code outside of a program that does not need HTML.
• Use the code outside of a database because you only need the business logic.
• Use the code to just get data because the business logic is invalid in that situation.

Small and focused code should help to provide Consistency

It was pointed out to me by /msg that in my "How many arguments?" example above, I made two changes between the two examples, and it was postulated that only one of these, the additional whitespace, contributed to whatever extra clarity was evident.

By way of further investigation, in which of the following is the number of parameters clearest to your eyes?

• someFunction( someVariable, someOtherVariable, andYetAnotherVariable, andOneMoreFor, luck )
• some_function (some_variable,some_other_variable,and_yet_another_variable,and_one_more_for,luck)
• someFunction (someVariable,someOtherVariable,andYetAnotherVariable,andOneMoreFor,luck)
• some_function( some_variable, some_other_variable, and_yet_another_variable, and_one_more_for, luck )

---

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.

"Too many [] have been sedated by an oppressive environment of political correctness and risk aversion."

The last one, definitely. :-)

1st & 4th, my favourite one BTW, are much easier on the eyes.

There is one more variation ...

some_function
(
  some_variable , some_other_variable , and_yet_another_variable
, and_one_more_for , luck
)
[download]

My touchstone for assisting in deciding what is readable in code is "how (sensibly) close to prose is it?". My justification is that what most of us read most, and are therefore best at parsing, is prose. Applying similar criteria for use of white space and "flow" surely has some benefit.

On the other hand a good friend of mine says that code is more like mathematics and that we should eschew (horizontal) white space where ever possible (although we agree on indentation style).

Before I learned Perl K&R indentation was complete anathema to me and I could see no justification for it what so ever. For Perl K&R seems to be a natural fit and that is what I have come to use. Although readability isn't generally a function of the language, some languages impose their own natural style, some even force a style.

In the past when I was more often proof reading other people's code I would fiddle with the formatting - not because that was "the right way", but because it helped me focus on the structure of the code and more easily grok it. For some reason this seemed to upset some authors. I wonder why? ;)

Some of the OP might be better described as a comentary on "maintainability", rather than "readability" (especially the variables/data structure section), although the two are rather tightly coupled.

My touchstone for assisting in deciding what is readable in code is "how (sensibly) close to prose is it?"

Yikes! There's probably way more unreadable prose than unreadable code.

-derby

On the other hand a good friend of mine says that code is more like mathematics and that we should eschew (horizontal) white space where ever possible (although we agree on indentation style).

As a mathematically inclined person, I'm of the school of thought that code is often much like Mathematics too. Still I can't understand the alleged implication that "we should eschew (horizontal) white space", which is generally not the case except perhaps in some specialized areas like Universal Algebra or Formal Languages. But otherwise careful trimming of whitespace does play an important role in mathematical typesetting, which in turn is a refined art. (Made much more accessible by Dr. Knuth's work! - To whom we all owe so much!!)

I think one of the most important concepts to take from programming is replacing abstract code with a function name that describe the work it is supposed to do. For example, I came across this code,

$fee = ($tfee / 100 + $sfee/100 + 0.0000001) * 100
$mfee = 200 if ($fee >= 100);

$fee = $mfee if $mfee;
[download]

I don't even know what this does or why it is doing it. If they had done something like this, I would have a basic understanding of the what they are trying to accomplish.

$fee = determine_maximum_fee();

sub determine_maximum_fee {
  $fee = ($tfee / 100 + $sfee/100 + 0.0000001) * 100
  $mfee = 200 if ($fee >= 100);

  $fee = $mfee if $mfee;
  return $fee;
}
[download]

To me, the difference between a good developer and a bad developer is being able to break code into functions that explain what the program is supposed to be doing. Something most beginning programmers do not understand.

Update: Changed sub determine_total_fee to sub determine_maximum_fee(), thanks to the Anonymous Monk for pointing out the error

$fee = determine_maximum_fee();

sub determine_total_fee {
[download]

Refactoring error? Is it determine_maximum_fee() or determine_total_fee? And that name that is overly verbose.

  $fee = ($tfee / 100 + $sfee/100 + 0.0000001) * 100
[download]

...what in the world is this doing? If I had to guess, I'd say it is a hack to misuse floating point numbers, instead of using something like Math::Currency, although I'd expect to see some calls to int(). And it diddles with global variable $foo.

  $mfee = 200 if ($fee >= 100);
[download]

...refers to global variables $mfee and $fee. And $mfee is non-descript. And we should at least have a comment explaining the magic numbers 100 and 200.

  $fee = $mfee if $mfee;
[download]

...this is seems like it is probably a horrible hack to avoid warnings about undef.

  return $fee;
}
[download]

I'd probably not refactor into a subroutine, instead using a proper data type and something like...

use constant BREAK_POINT => 100;
use constant BONUS_FEE   => 200;

my $total_fee = $tfee+$rfee >= BREAK_POINT ? BONUS_FEE : $tfee+$rfee;
[download]

You do bring up some good points about the code, however the problem is not with the code or its execution but its context. By moving the code into a function it should help declare a context of what is going to happen even if it hides what it is exactly doing.

I don't see your sentiment (which I agreed with) reflected in your modifications to the example. To my mind, breaking it into understandable functions would end up more like:

# with this level of modularity almost anything is readable!

sub determine_maximum_fee {
    #
    # functional description goes here
    #
    $fee = Roundup( Sum( @_ ) );
    $fee < 100 ? $fee : 200; # all 100+ fees become 200
}

sub Roundup { 
    #
    # Increase just barely to avoid any rounding down problem
    #
    100 * ( ($_[0]/100) + 0.0000001 );
}

sub Sum {
    #
    # needs no description.
    #
    my $result=0;
    $result += shift() || return $result while (1);
}
[download]

__________________________________________________________________________________

^M Free your mind!

APL? I had a friend (who was involved in building the engine monitoring software for the Rutan Voyager) described APL as a "write-once" language.

I don't think coding for readability and coding for maintainability are that much different. In either case, the program has to be written for an audience, and the chances are the audience will be less skilled. This may mean eschewing perfectly valid Perl, such as multiple statements on one line, or leaving in syntactically meaningless white space, or (horror!) putting in use English;, or adding parentheses that are not strictly needed.

$x =  $a
+$b
+$c;
[download]

I tend to keep my copy of Kernighan & Plauger's The Elements of Programming Style near to hand. Despite the examples being mostly in PL/1 and FORTRAN-66 (pdf file), most of the basic concepts are still applicable.

Probably the most extreme version of "readable code" is Donald Knuth's Literate Programming. I've never tried it (has anybody here tried it?)

I tend to dislike the practice of splitting long lines before operators,

Well it depends on the situation in your example it is not such a big deal. However, problems occur when lines tend run long. Example:

# Long line
my $absolutely_very_long_value = $value_reference->{$first_record}{$se
+cond_key}{super_property} + $value_reference->{$second_record}{$secon
+d_key}{super_property};

# Split Line
my $absolutely_very_long_value 
  = $value_reference->{$first_record }{$second_key}{super_property} 
  + $value_reference->{$second_record}{$second_key}{super_property};
[download]

I think the worst example for a long-line is something like this,

my $print = qq~
# HTML that goes on for 30+ lines
# This some more text here. text text text text text text text~ if $in
+s{save_changes};
[download]

I could have strung up the original programmer for this. This sort of syntax you may not even know you are working on a if statement. You don't see it unless you page down or you have to scroll all the way to the right.

Well it depends on the situation in your example it is not such a big deal. However, problems occur when lines tend run long.

I just prefer to split lines after operators.

In your example, my code would look like this:

# split line
my $absolutely_very_long_value =
   $value_reference -> {$first_record}{$second_key}{super_property} +
   $value_reference -> {$second_record}{$second_key}{super_property};
[download]

emc

At that time [1909] the chief engineer was almost always the chief test pilot as well. That had the fortunate result of eliminating poor engineering early in aviation.

—Igor Sikorsky, reported in AOPA Pilot magazine February 2003.

I came across the technique while reading Hanson's C interfaces & Implementations. By the way the book is a very good read (it abstracts and amplifies the techniques used in the creation of lcc). At least for books it seems quite useful. As far as using it for real in code, I don't know, you will have to teach your editor to put a link to code, and to present whatever is linked in-place in a different font say. Mean IDEs could even replace the code by a function! ;)

cheers --stephan

Not so much a comment on what is readable code (I cuddle my elses - so what do I know :-) but a tip on figuring out when it isn't that I've found very useful over the last few years.

Treat comments as a red flag.

Your argument          is wrong.
My     argument
Is
    Right.
Perl is as readable as poetry.
Your
Just
Not            A
      Poet.
[download]

Crude, but it usually got the point across. Languages are never inherently readable, the writer of a document creates readability vis a vie their own personal writing style. Some people have a hard time understanding poetry, but should that mean English is inherently unreadable? A child might not be able to forge a grammatically accurate sentence, does that mean their language is difficult to understand?

What it comes down to is this: there are programmers who know how to write code for other people to read, and programmers who don't. You could write complicated code in any language without ever creating a new line because (generally) the compiler doesn't care. Perl just extends that.

Perl isn't an unreadable language, it just has a very understanding interpreter.

I'm in the group that finds Python less readable than Perl (or Ruby). I find Python's white space rules far too reminiscent of IBM's JCL. Perhaps oddly, I also find COBOL less than readable, mostly after being confused by nested block if's ending on a single period.

emc

At that time [1909] the chief engineer was almost always the chief test pilot as well. That had the fortunate result of eliminating poor engineering early in aviation.

—Igor Sikorsky, reported in AOPA Pilot magazine February 2003.

This gets exactly to brian's point. Languages are not inherently more readble than others because of these design choices. I have not used Python, but I absolutely love Haskell, which has a similar layout rule to Python's. To me, knowing that my (or more importantly, someone else's) module won't even compile if a block is indented inconsistently is a great relief. For others, it may not be so significant.

If only that were true...

if DEFCON == 1:
    soundAlarm()
launchMissiles() #oops
[download]

I used to work in a company that programmed entirely in Forth. Yes it was a long time ago. In Forth there were not any types at all. And zero error checking. Forth tended also to be extremely terse. On account of that everybody who wrote Forth code very soon developed their own private dialect...which no other Forth programmer anywhere could easily read.

That situation is doubtless contributory to very few people even having ever heard of Forth today. Yet I do remember a certain liveliness of freedom those lack of restrictions afforded. And I remember enjoying them. Perl's own inbuilt freedoms were a large measure of what lured me to it originally. I shouldn't enjoy to see them trimmed too severely back. That would be saddening, I think.

I did have a rather short affair with Perl Critic. It did not much inspire me to run out and buy the book from which it cites most of its rules. At first I tried to take all its advice. And the results to me looked hideous. Having started out in Forth, I find Perl's flexibility, broad as it is, refeshingly restrained. But I shouldn't want it any tigher. I just do not see the point of having to do "if (bar) {foo}" always in favor of "foo if bar" for no better reason than to prevent C++ folks from being shocked by it.

My current fling is with a new book entitled Higher Order Perl which promotes the idea of functional programming in Perl. The first two chapters alone are worth the price of the book. The section on using dispatch tables has done more to make my code more readable than Perl Critic was able to do, I rather tend to think.

How utterly refreshing.

---

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.

"Too many [] have been sedated by an oppressive environment of political correctness and risk aversion."

Be well,
rir