[TimothyFitz]

"This method takes a foo object, applies HTML encoding, and returns an array of the original and the clean code." could be a 3-line unit test that's just as clear to read, but has the side effect of actually being true instead of maybe being true!

I would consider that comment just as bad as the ones in my examples, but maybe not quite as obviously so.

[makmanalp]

The main benefit of comments that you seem to be missing is that they are in the right context. Unit tests, while useful and required, make for boring reading and are not right where you need them. If I need to open up a separate file and scroll through tons of other tests to find the unit test "docs" on a function, you've lost me already.

[randomdrake]

Of course a better comment could be written. I was using a short and concise comment to illustrate how you can gain a huge amount of understanding in a single line versus parsing a long function definition. Other comments here make suggestions for writing good comments.

[endgame]

> could be a 3-line unit test that's just as clear to read, but has the side effect of actually being true instead of maybe being true!

It also has the side effect of being in a different file to the one you're trying to read.

[makmanalp]

Hey, actually, I think I found exactly what you want, maybe!

http://docs.python.org/2/library/doctest.html