[thelist] Basic Documentation Questions

Jason Lotito jason at clockmedia.com
Fri Feb 8 12:22:01 CST 2002


---- Original Message -----
From: "rudy" <r937 at interlog.com>
To: <thelist at lists.evolt.org>
Sent: Friday, February 08, 2002 12:21 PM
Subject: Re: [thelist] Basic Documentation Questions


> > /* Make all our keys lowercase for consistency */
> >    $new_data = $this->keystolower($data);
> >    /* Loop through each transaction */
> >    foreach ( $new_data as $key => $transaction )
> >
> > In the style above, you can pretty much grasp what we are doing at
> > each stage.  Commenting like this helps out tremendously in the long
run.
>
> hi jason
>
> great advice
>
> however, those two examples are rather poor (i realize you just used them
> to illustrate inline comments)
>
> i don't know what language that was, but assuming i knew it well enough to
> try to maintain it, i would find those comments superfluous
>
> working code is not the place to be telling me that "keystolower()"
> translates keys to lower case, or that "foreach" performs a loop

Yes, you are very much right.  I pulled that out of code that I am actually
working on, and didn't bother to actually read what I was sending.  I had in
fact recently moved the keystolower() code into its own function, and the
code is still going through development.  But you are right, comments like
that are in fact, counter productive.

I think this brings up a good point though, about commenting while you
write, and maintaining the comments.  Keeping comments up to date is rather
important.  I know people who write comments after they have written
everything.

The problem is, in the real world, we are often asked to stop working on
something to do something else real quick (this 'real quick' can be anything
from 1 hour to 1 week, or god forbid, even longer).  Maintaining your
comments with your code is important.

If you make changes to your code, make changes in your comments if need be.

Another suggestion, one I got from a colleague about a year ago, is his
"Optimization comment", as he called it.

His idea was simply that if you wish to optimize and streamline your code,
often it becomes unreadable (this is not always the case, but I hope you
know what I am referring to).  He decided that sacrificing speed for
readability is cheap, especially when you have comments.

What he did to solve the problem was actually quite nice.

Usually, when you optimize code, you are not writing new code, but changing
existing code.  What he would do is move the existing code into a comment,
and then add the optimized code.  Being able to see a readable copy of what
the optimized code does, he said, would help out a lot.

Rudy, thank you for pointing out the quality of my example (and also
understanding that it was merely an example).  It brought out some good
examples.

Overall, comments should be clear and concise.

I pretty much understand that you could tell what my code was doing, without
the comments.  I call this Self-Commenting code.  Basically, code that is
written in such a way that it becomes self commenting.  Anyone can read the
code and tell you what its doing because of the naming scheme, the way its
written, etc.

And just for reference purposes, the code was PHP code for a banking and
transaction system.

Jason Lotito
Programmer & Developer
Clockmedia Inc.
Designing Tomorrow's Games, Today!
1-877-625-6256
514-908-2800
Fax: 514-908-2803




More information about the thelist mailing list