First of all, I think this is a matter of (personal?) opinion, so probably we'll see a pretty interesting discussion.

I generally agree to your idea: "Maintainable perl code can be understood or figured out by a programmer that has invested the time and effort to learn and understand the language. But it should not require 10 years of Perl under your belt (or dress).", but I think there is more to it.

The art of writing maintainable code, in my opinion, has also a few subtle requirements (not that I am an expert myself, even as I am expected to write maintainable code). It is not only that the future programmer has to understand the code. The programmer must understand what we're doing with the code: the algorythms.

I think that in this respect, the different ways of comments available in Perl (inline/EOF POD and regular # comments) shine above the rest.

Let's see an example of algorythm vs code complexity at play. The problem is a very simple one, sort a list in random order. The relevant piece of code might look like:

for (my $i = @list; -- $i;) {
    my $r = int rand (1 + $i);
    @list [$i, $r] = @list [$r, $i] unless $r == $i;
}

[download]
or 
@list = map { $_->[0] } 
sort { $a->[1] <=> $b->[1] } 
map { [ $_, rand(1024) ] } @list;

[download]
(I stole the first one from Re: Randomize an Array to get an unbiased piece of code) Now, the choice of which is easier to understand is a personal one. Both have simple algorythms behind. But a not-so-experienced programmer facing any of the two, might get confused unless a bit of help (a hint, if you will) is present, probably in the form of a helpful comment.

I personally believe that the second form, using a Schwartzian Transform is both, daunting for beginning programmers and hard to see in other programming languages such as C, where an approach such as the first one is more likely to be seen. A programmer coming to Perl from C, might see the second alternative as quite unnatural for the problem, and therefore would have a harder time figuring it out.

To summarize, my personal way to (try to) write maintainable code, is to suppress the desire to compress my code shaving keystrokes beyond a certain point, and instead focus on doing things in ways that are both natural an easy (easier?) to understand to the new programmer we might hire tomorrow. I also try to spend reasonable time writing the documentation. Most of the time, I write all the documentation before the first line of relevant code, which also helps me figure out how to sketch orthogonal/complete/clear semantics.

Just my 10^-2 cents on this thought issue :)

In reply to Re: What is maintainable perl code? by fokat
in thread What is maintainable perl code? by disciple

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.