SPUG: One Python users' view of Perl

[Michael R. Wolf]

What's your criteria for deciding whether to make better comments or
refactor the code to be more readable?  They both have merit.  I'm
interested what your balance point is.

For example, I used to write code like this.

return $counter++;   # return the pre-incremented value

1 perl expression
1 sneaky 
1 comment
-----------
3 cognitive chunks

I now dispense with the idiom

$original = $counter
$counter++;
return $original;

3 perl expressions
0 comments
----------
3 cognitive chunks 

Zero chance that the comments are out of sync.  With the introduction of a
new variable to explicitly code what was otherwise implicit.

I guess that in this case, if it's as easy to come up with good variable
names, I'd prefer to introduce more Perl (in baby steps) than to try to
capture that (less efficiently) in English.  English was never designed to
capture the kinds of nuance that Perl was designed to.  I'll use Perl when I
can, English when I have to.

Of course, there's no added value to this kind of comment.  I'm currently
fighting this battle with a customer.  It's my belief that we should comment
the business logic, not the syntax.  If the reader doesn't understand syntax
(as appropriately formatted), comments are not likely to help enough to make
them worth the clutter.

if (condition) {
   block;
   .
   .
   .
   .
} # end if



-- 
Michael R. Wolf
    All mammals learn by playing!
        MichaelRWolf at att.net

> -----Original Message-----
> From: spug-list-bounces+michaelrwolf=att.net at pm.org [mailto:spug-list-
> bounces+michaelrwolf=att.net at pm.org] On Behalf Of Andrew Sweger
> Sent: Thursday, June 14, 2007 8:26 PM
> To: Jules Agee
> Cc: spug-list at pm.org
> Subject: Re: SPUG: One Python users' view of Perl
> 
> On Thu, 14 Jun 2007, Jules Agee wrote:
> 
> > Andrew Sweger wrote:
> > >
> > > Forget others that come after me. I find myself (regardless of the
> > > language) using longer expressions of what I'm trying to do in the
> code
> > > just so *I* have a hope of understanding what I'm doing (or trying to
> do).
> >
> > Once I even resorted to adding a comment explaining what a piece of code
> > did.
> 
> I really should not reply because I'm sure I'll just end up fanning some
> flames. But then my wife says I ain't that smart anyway...
> 
> I like comments that give me hints on particularly dense or idiomatic
> *little* bits of code (and hope the comment stays in sync with the code!).
> The other kind of comments I like are like chapter headings for long
> procedural sections to help identify how the problem is broken down.
> Otherwise, I prefer to read the code itself since it's responsible for all
> the action. (I am _not_ referring to documentation or POD.)
> 
> --
> Andrew B. Sweger -- The great thing about multitasking is that several
>                                 things can go wrong at once.
> 
> 
> _____________________________________________________________
> Seattle Perl Users Group Mailing List
>      POST TO: spug-list at pm.org
> SUBSCRIPTION: http://mail.pm.org/mailman/listinfo/spug-list
>     MEETINGS: 3rd Tuesdays
>     WEB PAGE: http://seattleperl.org/