The worth of comments

[Neil Cerutti]

On 2011-05-28, Roy Smith <roy at panix.com> wrote:
> 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).

That's an excellent illustration of bad code hid by a bad comment.

Perhaps better:

def foo():
  raise IndexError()

-- 
Neil Cerutti