Well, I can't comment on the meaningfullness of the name as you've removed it, but the intent of the code is clear. Even if the formatting is a bit awkward. (operators at the end of the lines? Come on! This ain't Ruby ... you don't have to hint the compiler that we are not done with the statement yet!)

This, in my humble opinion, rather readable snippet of code is supposed to be used by the sort() routine and specifies that the AoA is to be sorted by 3rd, 2nd, 1st, 0th and 4th columns in this order of importance. You might want to use constants instead of the numbers to specify the columns, but that's about the best you can do.

Unless of course you want to factor out the indices and use something like

sub SUB_NAME {
 for (3,2,1,0,4) { # sort by the specified columns
  my $res = ($a->[$_] <=> $b->[$_]) and return $res;
 }
}
[download]

Update: Oops. Good catch merlyn, thanks. A reminder to test the code I post here.

my $res = ($a->[$_] <=> $b->[$_]) and return $res;
[download]

Which doesn't work because $res isn't declared until after the end of the statement! Doh!

Under use strict, this would fail, unless you happened to have another $res in scope, and then it'd be returning that, some of the time. Spooky.

-- Randal L. Schwartz, Perl hacker

Update: Argh! see blazar's reply below

Better would be:

sub SUB_NAME {
   # sort by the specified columns 
   $_ = $a->[$_] <=> $b->[$_] and return $_ for 3, 2, 1, 0, 4;
   return 0;
 }
}
[download]

;)

---

DWIM is Perl's answer to Gödel

Better would be:

sub SUB_NAME {
   # sort by the specified columns 
   $_ = $a->[$_] <=> $b->[$_] and return $_ for 3, 2, 1, 0, 4;
   return 0;
 }
[download]

Modification of a read-only value attempted at 614055.pl line 3.

I can't comment on the naming of the sub, but the substance looks fine, albeit with somewhat quirky indentation. It is clearly a comparison function used to sort a two dimensional array where column importance (for sorting purposes) is in the index order 3, 2, 1, 0, 4.

It might be nice for a comment to say "sort by Name, Social ID number, street address, then eye color", but commenting "sort by columns 4, 3, 2, 1, 5" adds nothing to the code and would likely cause confusion.

There are a few things that could reduce the possibility for error. Using named constants for the column indexes or using a hash for the column entries instead of an array would go a long way to making the code more robust, but wouldn't much change how obvious the intent of this particular routine is.

There may be many nasty things in the code that you are looking at, but this example is really not so awful. The major thing it needs to make it acceptable is a good name.

I think you might have done better by not including any code at all. I was hoping for this in fact. Your meditation seems to boil down to dragonchild's current signature:

L~R, you nailed it. In retrospect, I shouldn't have posted the code, because everyone focused on it, which was besides the point.

I believe self-documenting code is something of a fallacy. Yes, it was easily recognized as a sorting routine. Yes, it sorted two array references based on out-of-order selection of sub-elements within each. We could all pick up on that.

The point I was trying to make was one about the value of taking the time to do things the right way. In this case, there's nothing explicitely wrong with the code. The problem is the fact that depending on people's ability to read code, no matter how self-documenting you make it, is a cop-out.

Like everyone else, I look at it, and go "sure, it's a sorting routine, sorting on sub-elements of two array-refs". But immediately, I think of the following questions:

• Why?
• What data is actually being sorted?
• Is this intended to sort one specific set of data structures, or is it more general?
• Why is datat sorted in this particular order?

And this is where I get annoyed. Because this sort sub isn't documented. Because the surrounding code isn't properly documented. Because the only documentation in this 500-line script is a couple of minor lines at the top about inputs and outputs. And in the end, this sub shouldn't even exist, because as far as I can tell, it's not being used.

Sure, code can be self-documenting, but to a point. This "self-documenting" code now requires me to spend far more time going through the code to figure out what is going on & why than it should. A car's motor is "self-documenting" in the same fashion - sure, I can figure out where everything is & diagnose the issue eventually, but the shop manual makes my life a lot easier.

And so, back to my original rant. It's not just about writing clean, easy-to-understand code. The 'easy-to-understand' part is not just code, it's comments. Documenation. Explanation. Motivations. I'm tired of the pseudo-macho justifications for not writing documentation. Write it. Because otherwise I'm just going to come back & drive you nuts, forcing you to explain why you wrote every last method the way you did.

Just playing devil's advocate: I don't think it's pseudo-macho or any other kind of macho to leave comments out of code if the code in question is self-documenting by the way it's written. Good code, IMHO, is a translation layer that sits between the human and the computer, so when it's done right it doesn't require a whole lot of explanation in the form of comments. A contrived example:

  sub refuse_to_cooperate {
    my $beef_with_user = shift;
    print qq(I'm refusing to cooperate with you: $beef_with_user\n\n);
    die "Don't go away mad, just go away.";
  }


if ($username eq 'gwbush') {
  refuse_to_cooperate(qq(Spoiled momma's boys should not be given armi
+es to play with.));
}
[download]

Commenting that would add clutter without value. $beef_with_user could have been left out by simpling shifting off of @_ when needed, but then the function would have been slightly less self-documenting.

My rule of thumb: Provide POD for the interface, self-documenting code whenever possible, and comments when I'm typing before I'm truly done thinking. If I've thought my way through a thing sufficiently, then it's probably going to be self-documenting (AKA Living Documentation) when I'm done as a natural consequence.

If you can't read code, you should not be modifying it! Sure, a little documentation about WHY does some function exist is often helpfull, in case of this function I do think the only needed documentation is the name. And if at all the comment about why is the data sorted this way belongs not next to this function definition, but next to its use. Though it's hard to say as this is the only thing we've seen from the code.

Jenda


Support Denmark! Defend the free world!

You're going to have to support it in the future, document it. At least say *something* about why this block of code exists.

My take on this has always been that good code is self-documenting. There are intrinsic limits, though, to how good some code can be, and in those cases yes: document it. Clearly, early, abundantly.

Self-documenting code is good, yes. Necessary, even.

But at best it can only tell you *what* the code does. Sometimes the *why* is obvious, sometimes not. A good function name can help, but still....

Personally, I like to see even a one-line blurb on why the function exists. It helps me build (or re-build) that mental map of the system.

Something like:


# Data comes back from the DB sorted by x,y,z.
# If the user wants a different order, here's where we do it.
[download]

Personally, I like to see even a one-line blurb on why the function exists. It helps me build (or re-build) that mental map of the system.

But of course you're a bibliophile! ;-)

Documentation is an antibiotic for bad code.

Bad programmers avoid documentation like it were the plague!