Link Details

She's right that documentation is a second artifact (wet not DRY) and that it often indicates "bad smells" (you know, the comment where somebody apologizes for doing something bad.)

I agree with her that documenting "nouns" can be as much a problem as it is a solution. I think that documenting "verbs" (processes) is essential to a having a smooth running ship.

Her post is pure rubbish.

I am only barely voting up because I can agree that documentation *can* become more of a pest. However this issue is one of the long-fought debates in the world of software development and I acknowledge both sides.

just follow the old adage, comments should say "why" not "what"

I tend to agree. It always seems to me that well-written code is accused of being simple and therefore needs no documentation. Poorly written code seems to force the team to have documentation or else no one knows what it does.

In a worst-case scenario, the author of the bad code "doesn't have time to fix it" and forces the rest of the team to write the documentation which makes it look to the manager that the coder really knows what they're doing since they can write such complex software.

Good luck fixing that mission critical piece of code when the authors on holiday and you don't really understand the api/language/approach.

Bad comments are as bad as no comment - you'll get no arguement from me on that point. But you can't throw the baby out with the bathwater just because you don't like changing the nappies.