httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ben Laurie <>
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.



Ben Laurie            |Phone: +44 (181) 735 0686| Apache Group member
Freelance Consultant  |Fax:   +44 (181) 735 0689|
and Technical Director|Email: |
A.L. Digital Ltd,     |Apache-SSL author
London, England.      |"Apache: TDG"


View raw message