httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ben Laurie <...@algroup.co.uk>
Subject Re: cvs commit: apache-1.3/src/modules/standard mod_autoindex.c
Date Tue, 07 Jul 1998 21:54:32 GMT
Jim Jagielski wrote:
> 
> Dean Gaudet wrote:
> >
> > To be honest Ken, it's not necessary to comment every line of code.
> > I find folks learn that when they're in school -- it's something that
> > the schools get completely wrong.  Grading proportional to the number
> > of comments is a crime that leads to folks who comment every line of code.
> >
> 
> I've always found that the code that's commented the least, is the one
> that's also the most convoluted and hardest to understand. I consider
> comments a "kindness" to any future maintainers, not so much to
> describe WHAT the code is doing, but rather WHY. I don't know of that
> many regular humans who haven't come across a chunk of code they did
> a few years ago and scratch their heads and say "Now why in the f*ck
> did I do THAT?" :) :)

If we're going to get into a comments debate, I should say this:
comments are generally bad. They either state the obvious, in which case
they shouldn't be there; they're just taking up screen and brain
acreage, or they're wrong (or at least potentially wrong). The rare
exception, IMO, is a case where the code has a subtlety which is not
easy to appreciate. A comment should explain the subtlety. My rule of
thumb is that when I find myself puzzling over how the hell the same bit
of code works, for the second time, I add a comment. The comment should
be as short as possible, and give just enough clue to avoid puzzling for
too long. But puzzling is good - if you believe the comment it prevents
you from understanding the code.

Cheers,

Ben.

-- 
Ben Laurie            |Phone: +44 (181) 735 0686| Apache Group member
Freelance Consultant  |Fax:   +44 (181) 735 0689|http://www.apache.org/
and Technical Director|Email: ben@algroup.co.uk |
A.L. Digital Ltd,     |Apache-SSL author     http://www.apache-ssl.org/
London, England.      |"Apache: TDG" http://www.ora.com/catalog/apache/

WE'RE RECRUITING! http://www.aldigital.co.uk/recruit/

Mime
View raw message