The worth of comments

[Roy Smith]

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

> When trying to find a bug in code written by sombody else, I often
> first go through and delete all of the comments so as not to be
> mislead.

I've heard people say that before.  While I get the concept, I don't 
like doing things that way myself.

>> The comments reflect what the author _thought_ the code did
> _at_some_point_in_the_past_.  What matters is what the code actually
> does at the present.

I don't look at it that way.  Most of the comments I write are to 
document interfaces, i.e. what the code is supposed to do.  That's the 
contract between you and the code.  If you call me with arguments that 
meet these conditions, this is what I promise I'll return to you (and 
what side effects I'll perform).

One reasonable definition of a bug is something the code actually does 
which differs from the documented interface.  Unless you know what the 
code is supposed to do, how can you possibly look at it and say whether 
it has a bug or not?  For example, take this function:

def foo():
   l = [1, 2, 3]
   return l[3]

Is this code correct?  I'll bet most people would look at this and say, 
"I'm not sure what he had in mind, but whatever it was, this has to be a 
bug because he's indexing past the end of the list".  Well, what if I 
showed you the interface contract:

def foo():
   "Raise IndexError.  This is useful as a testing fixture."
   l = [1, 2, 3]
   return l[3]

Now it's obvious that the function does exactly what it's supposed to do 
(even if it's not the best way to do it).