You’re CHOOSING to be irritated about something of no consequence as an excuse to distinguish yourself as a commenting ninja.
Lots of verbose commenting is FUN and makes coding EASY!!!
YAY for FUN!!! YAY for EASY!!! YAY for COMMENTS!!!
Only an idiot would lose sleep over whether their comments aren’t as hip or succinct as someone else would like.
Next post: RTFM NOOB!!!
I can’t believe what I’m reading with some of these comments. Do you people who advocate using zero comments actually work at real companies that make real software?
You realize other people are going to have to read your shitty code eventually right? (and if you are the kind of person who thinks you don’t need to write ANY comments then I assure you everyone else thinks your code is shitty) When I have to fix a bug and the person who originally wrote the code didn’t have the courtesy to write a few comments I want to break things.
It makes good sense to put in comments indicating exactly what part of the code has been changed, by whom, on what date, and for what reason. Put in the project number, ticket number, or whatever else is relevant. That way, if a bug fix affects something else later on, or has to be refined further to account for changes in the real-world requirements, you can save the next person a lot of time and effort.
I have come back to this article several times, because it sounds a lot like what the XP methodology uses. Each time I end up thinking that at first glance this sounds like a great idea, but in practice it just doesn’t work. Source code is not a replacement for documentation.
I think the real issue is not comment are good or bad.Issue is how we use comments in code.
I believe on the importance of commenting in code.It saves time, clarify complexities, easier maintainability and make code fresh cream cake for other team members including new comers. Let me explain this. Say, If I am writing a code, actually i am not remembering it.I am just using logic from my mind and developing a software.After 3/4 weeks when I review my own code, I will not able remember exactly what area of code doing what (if its a bulk code).At that time self-explanatory naming convention and comments describing the whole story in files will help me to understand it quickly. Thus, I will not use my brain resources on useless effort to recall on own hand-written code and keep my mind fresh 
Bastijee, check out the Fowler refactoring book on extract method / method naming. Jeff mentions this refactoring above. You might code even faster (and do less rework) if you type fewer comments : )
Whenever we make an assumption about the external domain - something not intrinsic to the code - then a comment helps spread the knowledge to other guys on the team!
// Null relation Id = uber account
if (!account.RelationId.HasValue)
{
account.Name = String.Format(strong{0}strong, account.Name);
}
Hello…this is angel visiting first time to this site and find it very interesting.
How about using a program that can condense comments. They can be as detailed as the person wants it to be, and it won’t clutter the code. I personally use very little commenting, but I’ll comment information about what the function/class does at the top of it in simple terms. The more modularly you program, the nicer it becomes - within reason.
There are some interesting points in this article, and particularly in the responses to it. In fact I think it’s worth pointing out that a more thorough understanding of the issue can be found by reading the extensive comments on this article. 
well, that is good to knwo
It’s OK to end up with comments in your code, but never, ever start with comments.
Just as others, who have already mentioned it, I too write comments before writing a line of code, as a way of helping me think things through; and I see nothing wrong with that.
I find a lot of your blog posts useful for generating discussion - it’s your frequent dogmatic conclusions that make me wonder if your head has grown a bit big…
Well, lately I realized that starting to write code with comments doesn’t help as much as starting to write code with unit tests first.
And that’s why I like TDD.
You’re way off the reservation with this one.
With the Newton-Raphson approximation comment,you knew which method of approximation was being used. There is no way your refactored method name is clearer than that
And I find junior developers hardly ever write comments.
Also, we need to end this myth that code is EVER as clear as well-written English. This is patently false 100% of the time (your Newton-Raphson approximation example as proof is insane ).
That said, if comments are explaining obvious code (for some definition of obvious),then it’s probably not necessary. However, I’ve yet to be on a software project where too many comments/documentation/etc was an issue. I’d love to have that problem.
You’re a year late Jeff…
http://www.clanmonroe.com/Blog/archive/2007/06/04/commenting-your-code-is-bad.aspx
I believe comments are vital for explaining what you’re doing and why if it’s not INSTANTLY clear. That is, even if your routine is understandable after a minute of thinking the code through, it needs a comment because it’s not immediately obvious.
In your example, I agree that you should make that its own routine for clarity, but I still would have left the reference to Newton-Raphson approximation in there, no matter how you organised it. You cannot possibly believe that everyone will immediately understand that’s what it’s doing.
I like to think of the comments as integral to the story of the code - Combining the code and the comments, you can see what a routine is doing very, very quickly, and that’s important.
Comments are the what and why of the code, and the code itself is the how. When properly used, they slot together perfectly and have the ability to speed up development and debugging.
Comments at the start of methods and classes are possibly the most useful comments out there - they reduce the need for heavy commenting within the code itself, explain who did what and why (useful for corporate coding and maintenance), and when you combine them with something like doxygen it can save you a lot of time hunting down someone else’s code in a large code-bed.
In my experience there are developers who comment and like comments, and developers who have never given comments a proper chance and therefore hate it. Often developers take on a level of arrogance that says that their code is so perfect they don’t need comments, but you cannot forget that there are developers out there at all skill levels and if you really are a hot coder, most of those guys really won’t understand why you’re doing something in a certain way.
BTW, some of us are forced to go through code reviews with idiots who are not coders, such as IT auditors and management. With the comments, they can get by without you having to sit there painfully explaining every line to them!
Give comments a chance mate! If they’re not working for you, then your comments are BAD comments!
Sorry to say this, but: You seem to produce more coding horror yourself than you try to prevent other from making.
Advocating not to comment your code is really not helping. Not helping at all. I have seen so many functions, classes, methods and other stuff whitout comments, where I had to read it line by line to figure out what it was supposed to to.
Of course, in such a simple example as you have given, you can probably name the function/method appropriatly to document it. Of course you should always choose self-documenting names for all symbols in your code. But in general, it is impossible to document every aspect of a class or method just by naming it right. The name can give you a general direction what it might do, but in the end, you just have to document all its parameters, side effects, restrictions, error conditions and everything someone who uses the code could need to know.
Of course it has to be maintained, but its just part of the whole process. You have to maintain a user manual too if you change functionality or add a feature. You can not just say: Hey, I named that button or menu really well, so I doesn’t need to be documented anywhere. Again, this is true for simple cases (OK), but not in general.
Jeff, I urge you to rethink your approach here and not to advocate this any further. Try to think of the general case not just the simple ones (this applies to a lot of examples you have used in the past).
Seems to me that everyone who is advocating writing comments in code are doing so from a point of view that code is difficult to understand.
My view, is that if well written (and that is important) code is hard to understand then it needs a comment. But if bad code is hard to understand it needs to be refractor.
And refactor is not the same rewriting (as it seems a lot of people seem to think). Refactoring implies ‘no change in functionality’ and therefore should have the same regression testing requirements as slapping on a comment (which is after all still a change to the source file).
Commenting badly written code (instead of refactoring it and correcting the ‘badness’) just propagates the problem further down the line to another person who will have to read both the comment and the code later.
As I think one or two others may have pointed out (rather verbosely, haha), I also use comments fairly often to document design decisions.
My present example is a checkpoint system for realtime data, the logistics of which make my head spin. So there are little hints peppered around the provider class that explain, for example, why the end date of some checkpoint is not the same as the end date of its corresponding transaction. Or why the original and modified parameters are swapped in a certain call (I can just imagine someone reading the code, assuming that was a mistake, and proceeding to break one of the most critical components).
Of course, most of my smaller projects have no comments at all - they’re simply not complex enough to require them. There aren’t really any significant design decisions.
Actually, Jeff, in this case, I think both the original example and your refactored version are wrong. There should be a comment, but not the comment that’s there. The comment should answer the question: why are we using a hand-rolled square-root-approximation function when there’s already a perfectly good sqrt function in the math library?
How to dupe the world into thinking you are an Authority: Write lots of opinionated, loud blog posts on lots of subjects. It’s fast becoming clear that Jeff Atwood is not a skilled developer. In fact, as you watch his writing about stack overflow, it becomes very clear that he is flying by the seat of his pants and has no idea what he is doing. He even admits that he has some sort of pathological need for public attention in the last podcast. Sure, it’s entertaining, in a train wreck sort of way, but I sure feel sorry for people who come here thinking they are getting good advice and that Atwood knows what he is talking about.