The worth of comments

[Neil Cerutti]

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