The worth of comments

[Irmen de Jong]

On 28-5-2011 15:36, Roy Smith wrote:
> 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).

I don't see how that is opposed to what Grant was saying. It's that these 'contracts'
tend to change and that people forget or are too lazy to update the comments to reflect
those changes.

The comments you are writing, saying what the code is supposed to do, are only saying
what the code is supposed to do at the moment in time that you were writing the comment
and/or the code, are they not?

> 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?

Unit tests should tell you.


>  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".

I do agree that reading just that piece of code without other information, makes me
think that it is fishy. But:


>  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).

A month later the requirement changes: it should raise a ZeroDevisionError instead.
Someone modifies the code but leaves the comment (for whatever reason).

def foo():
    "Raise IndexError.  This is useful as a testing fixture."
    return 1//0

Unless there is a way to force people to update the code comment as well (which I'm not
aware of.. Doctests? dunno...),  you now have a comment that lies about the the intended
working.   In my opinion that is worse than what we had before (the function without
comment).


That being said, I do write code comments myself. Some of them are like notes, directed
to future-me or other future readers (remember that we do this because blabla, don't
change this to such-and-such because it will probably break xyz) and some of them are
stating the contract of the code (like you wrote above, about documenting interfaces).
I always try to avoid writing comments that duplicate the working of the code itself in
pseudo code or text phrases.  But humans make mistakes and forget things so after enough
modifications my code probably contains lies as well... :(


Irmen de Jong