That's no good. Your code is *way* too thick; a simple regex like that shouldn't really be worth commenting with such detail, but because your code is so condensed, they're necessary. And, whenever comments are needed with so short a snippet, its time to take a step back and wonder why.

When you need to perform a complex substitution, you should consider factoring out the code into a simple subroutine. It works wonders for readability; for instance, your example no longer needs comments, as the code is simple enough to explain itself.

my $sentence = ( join " ", @ARGV ) ||
    "Give me a sentence containing kilometers or miles or both.\n" .
    qq|   Eg (note quotes): "I live 6 miles from here."|;

$sentence =~ s/\b (\d+(?:\.\d+)?) \s+ (kilometer|mile)/ transform($1,$
+2) /xige;

print $sentence, "\n";

sub transform($$) {
    my ($amnt, $type) = @_;
    my ($switched, $to, $one) = ($amnt * 0.63, 'mile');
    
    if ($type eq 'mile') {
        $switched = $amnt * 1.6;
        $to   = 'kilometer';
    }
    $one  = 's' if $amnt == 1;
    
    sprintf "%.1f %s%s", $switched, $to, $one;
}
[download]

The point is very good and I agree and ++ed for that.

But why the prototype? And if you're going to use one, why are you calling the subroutine in a piece of code prior to declaring it, causing perl to complain that it's too early to have the prototype checked at that point?

Most of the time, you shouldn't use prototypes at all. There are only very rare circumstances which justify them, and I don't consider this one of them.

Makeshifts last the longest.

Whoa there! Like it says in the title, this is a stupid regex trick. It's not production code, nor did I pass it off as such; the regex itself for example doesn't stand up to certain types of numbers. I can write clean production code but clean that kind of mind numbing code day-in-day-out-3-for-loops-instead-of-a-Schwartzian-tranform-stuff is not interesting (to me) for discussions.

Update: (As the snippet says, this is "play" and not trying to solicit "fixed" code but more samples, which I'd still love to see, of what's possible within a regex, not what's correct in one's particular code style estimation. And I believe almost all code is worth commenting out.)

I can write clean code but clean code is not interesting for discussions

Actually, I'd argue the opposite. Messy code is useless (unless it reveals a bug) while clean code can be reused in many different ways to accomplish many different goals. Practical code is exponentially more interesting than 'messy code' can ever be.

There's nothing "tricky" about your code at all, other than the fact that it is messy. And you don't do anything spectacular with the regex either; the right side of a substituiton is a string, not a regex.

Also, most code is not worth commenting. In fact, in a perfect world, no code would need to be commented. Code itself should be self-documenting; algorithms and structure deserve comments and documentation, not code.