The worth of comments

[Roy Smith]

In article <irtm3d$qk3$2 at reader1.panix.com>,
 Grant Edwards <invalid at invalid.invalid> wrote:

> On 2011-05-29, Gregory Ewing <greg.ewing at canterbury.ac.nz> wrote:
> > Ben Finney wrote:
> >
> >> You omit the common third possibility: *both* the comment and the code
> >> are wrong.
> >
> > In that case, the correct response is to fix both of them. :-)
> 
> Only as a last resort. IMO, the best option is to fix the code so it's
> purpose and operation is obvious from the code, and then delete the
> comment.

This is a plausible(*) strategy for internal use software where all 
users have easy access to all code which depends on yours and are free 
to change interfaces willy-nilly.  That's not always the case.  Even on 
open-source projects, having stand-alone documentation is critical for 
usability, and certainly having stable interfaces is critical if you 
expect people to adopt your system and build on it.

(*)And, even in the case where it's internal code and everybody on the 
project has full and unfettered access to all the source, documenting 
interfaces adds to usability.  I've seen plenty of code which looks like 
this (pseudo-code):

Class1::f1() {
   return Class2::f2();
}

Class2::f2() {
   return Class3::f3();
}

Class3::f3() {
   return Class4::f4();
}

If you're trying to figure out what type of object f1() returns, you've 
got to chase down a long string of, "Well, f1 returns whatever f2 
returns, and f2 returns whatever f3 returns, and f3 returns whatever f4 
returns, and...."  Each step in that process might involve figuring out 
just where the heck the code for ClassN is.  And Cthulhu help you if 
some step along the way involves an indirectly referenced class or 
function so you can't even grep the source tree for the name you're 
looking for.