[randomdrake]

Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves.

So many times I have had to repair code in languages I wasn't quite familiar in or that was simply using methods I hadn't learned yet. Those comments were life saving.

Comments describing intentions of code also allow for someone to come by later and quickly and concisely understand what the code was doing and where it was going.

I cannot think of a single instance where parsing 65 lines of a function definition was ever quicker than reading:

This method takes a foo object, applies HTML encoding, and returns an array of the original and the clean code.

In the same vein, saying that Unit Tests are a replacement for comments just brings me back to my original assertion: I already am looking for help understanding the code base, so I should look at more code elsewhere and parse another long list of assertions?

Bad comments are bad like bad code is bad, or like bad pie is bad. But comments, code and pie aren't bad.

Please don't stop commenting your code because you feel like you can be more clever with the language instead. Someone may be much more familiar with the language the comments are written in. They may may need to do something with what you wrote.

Whenever I read some new reason why comments aren't cool or why some programmer has decided they[1] can just be clever with the language, I can't help but think they just don't have enough experience to know why and how comments can be absolutely necessary and fantastic.

[1] not saying this is necessarily true in this case, it's just the impression I get.

[grn]

Comments are useful when they provide information that is not in the code (e.g. rationale for the choice of an algorithm, source of a regular expression that parses an URL). Your example HTML encoding function can be coded as:

    def clean(foo)
        return [foo, foo.apply_html_encoding]
    end

The encoding logic should be contained in apply_html_encoding. The point is that most of the functions/methods that are 65 lines long are badly coded.

[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

[timwiseman]

I prefer to lean towards overcommenting, and I prefer that developers whose code I will have to work with later do the same.

But as you say, they need to be good comments, and comments that either describe intention or explain something in the language that might be rather obscure can be very useful.

[alexchamberlain]

Is that really quicker than reading return array(foo, foo->encodeHTML())?