Link Details

the retorts by the other commenters are enough for me.

That's a dangerous advice. We're not exactly knows for our documentation and communication skills, and I would be scared novice developer read this title and go thinking all they need to do is code. You can have bad comments, sure. But learn how to write good comments (read Code Complete or Clean Code) rather than equate comments with code smell!

yes, but this is coming from perfect world thoughtworks.

Although I generally don't agree much with this post, I find it an interesting read.

Nonsense. I haven't seen code without comments that can be understandable for developers other than the author (and sometimes not even for the author!)

I just read this http://www.geekherocomic.com/2008/11/12/real-programmers-dont-write-documentation/ ...pretty funny

I tend to agree with the guy.
To be honest.. comments have never helped me much in projects that I took over.
In fact.. they usually distract me..

You have to have a general idea what a project is supposed to do (high level design).
The rest is code reading+navigating for me. Code navigation is what REALLY helps speed up understanding a project for me.
(go to definition,find usages etc etc).

Javadoc style comments helps in libraries though. But those are more like integrated help-files.

i believe the mantra is the tests are the documentation. but all the tests document is the behavior, NOT the motivation or purpose of that behavior.

I disagree that comments == smell, but I'm in favour of making code self-documenting as far as possible. Turning large functions into many smaller functions does make everything easier to read, and I'm guilty of not doing this enough.

On the subject of using tests to document a system I disagree. They can show *how* to use it, but not why. They don't imply rationale. It is much easier to read through some well-written javadoc/equivalent documentation for methods and classes as an introduction than to read through the tests. Especially if your test-writing skills are relatively poor like mine :-(

Nonetheless this is a good post that provides some food for thought and is worth a read.

i agree, but the responses are much more worthwhile to read.
so if your short on time, skip over the blog and spend time on the responses.

You've hit the nail on the head here. The big problem here is the author doesn't acknowledge the fact that comments should aways tell WHY not how. Proper use of comments mixed with clear code shoud be the ultimate goal of all developers. I recently purchased his book and its good but thinking that all comments = code smell is short sighted at best. Unfortunately, some developers will use the advice given in this post to justify lazy coding completely lacking in comments of any kind; much to everyone's detriment.

i work with some thoughtworks contractors every day, and every day i argue for "why and when to use" comments...
sigh, i just cant seem to get through to them