Link Details

The author's examples of suitable comments are very similar to the type of comments suggested by those recommending readable code with minimal comments of design rationale. He even suggests descriptive code (like better method naming) can replace comments (and he gives an example). Which side of the debate is he on? The claim that beginning programmers who write bad code will somehow be able to write effective and useful comments is also dubious. The author finishes with a wish to not work with people who write minimal but effective comments in their code. Personally, I rather work with good programmers who write effective comments. The author is welcome to the rest.

I said in the article that I agreed with Jeff that descriptive names are a good thing. Descriptive names alone are *not* sufficient. My wish was to not work with people who feel that their code is somehow good enough that it does not require *any* comments. These people generally have an inflated opinion of the readability and quality of their code. I stand by my assertion that there is no such thing as code that is good enough to not require any comments.

You can make all the assertions you'd like, but code does exist that is good and clear enough to not require comments. I've personally seen it. A lot of it. And not necessarily code that I wrote. My opinion is...

Write good, clean, descriptive code (if someone has trouble with this, prefer development of coding skills over attempting to compensate by writing more comments)

Include comments where needed (typically for rationale or other contextual info not represented by the code itself).

I didn't have the impression that Atwood claimed that descriptive names alone were sufficient to eliminate the need for all comments. You even mention that he suggests that documenting rationale (the "why") can be a good reason for a comment. Which high-profile bloggers have advocated not writing /any/ comments for any purpose? There may be one, but I haven't personally seen this claim. That's why I wasn't sure who you were debating.

I don't think that Jeff mentioned documenting the "why", nor did I write that he did advocate that. It is me that is advocating documenting the "why", whereas you seem to be saying that this is not necessary, which I can't agree with. It's incredibly useful information for the maintenance programmer.

You are missing the point of my argument by suggesting that I am advocating compensating for poor code by commenting. I *agreed* with Jeff's basic premise and, as you pointed out, even extended on it by renaming some of his variables. And while Jeff may not have advocated never writing any comments, I felt that he was overstating his case against commenting.

When you say in your first reply "I rather work with good programmers who write effective comments" I am in complete agreement. I am not championing poor programmers, and if you are all for "effective comments", then what are we disagreeing about? :)

Take a look at Atwood's July 24th blog entry "Coding Without Comments" for his discussion of "why" comments. I assumed you were responding to that article.

You said "the idea that we should be aiming for some kind of perfect code that has no need for any comments is dangerous". Of course I agree, but I'm still waiting for a reference to who is making the claim you are disputing.

Yes, I was responding to that article. I just had a look at it again, I see that he linked to his previous post about "why comments" (which I had not read) without elaborating on it in the more recent post, so I missed what he had to say about that.

I'll concede that I have made a small leap from Jeff's position in that paragraph and I can see why you have interpretted it slightly differently from how I intended it to come across. I could have constructed the paragraph better to avoid implying that either Jeff or Steve were saying "no comments at all, ever" and still have made my point.

I can't change it right now because I'm on the front page of Digg and my server is melting under the load :(

Join CPAACTC (Computer Programmers Against Adding Comments To Code) -- I find that comments are more frequently lies than truths. All it takes is one automated refactoring to destroy the legitimacy of your comments. Comment where it makes sense, like in interfaces, or when you need to record business reasoning, but write code that documents itself! You will be much happier in the end! I've seen what happens when comments are used to describe behavior, and over time it is very ugly.

Joe,

I completely disagree, I maintain that my code is so attractive and obvious that non-programmers can read it and tell me what it does. That should be all of our goals. Software engineering is the only profession that promotes hand holding of people that aren't exerienced in the field by constantly translating what we are doing into what we consider words that are easier to understand.

Should everyone quit commenting? obviously some shouldn't, but it should be all of our goals.

Lincolnthree - good call, here is my article about the same concept - http://girldeveloper.com/waxing-dev/documentation-a-sure-sign-of-garbage-code/

sorry, Daniel, I disagree,