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