in reply to What is maintainable perl code?

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 :)

Replies are listed 'Best First'.
Re: Re: What is maintainable perl code?
by disciple (Pilgrim) on Sep 20, 2002 at 03:39 UTC
    First of all, I think this is a matter of (personal?) opinion, so probably we'll see a pretty interesting discussion.

    I agree completely that personal opinion plays a large role in what people consider maintainable code. OTOH, I have found that much opinion is merely in style and does not affect the maintainability of the code. I do recognize that there is a fine line there. Unfortunately I am always crossing fine lines. Just ask my wife. ;-)

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

    I agree. :-) I really like the commenting abilities in Perl.

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

      or

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

    [download]
    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.

    I agree, the first example is easier to understand. But, if one understands what each item in the second example does, then a complete picture can be pieced together. And if I didn't understand, I would read perldoc and/or books until I did. But I just consider that a cost of learning.

    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 agree except that I don't want to to avoid using an advanced technique which is quite elegant in order for a new programmer to understand it. The same thing can be done in VB. I can write something in VB that will confuse the heck out of new programmers, but it is an elegant solution for the problem. But this is where documentation helps dramatically (like you mention below).

    I also try to spend reasonable time writing the documentation.

    Thanks, I enjoyed reading your comments.

    -disciple
[reply]
[d/l]

In Section Meditations