Harrumph. I did check to see if anyone had already commented on the var names, but for some reason the web site only showed me the comments written up to Dan’s of 08:09 PM last night. Methinks there’s a naughty cacher somewhere on my slow link. Sorry! B-(
Jeff:
Comments are for the next guy who has to modify the code at 3 am when production is down and the original programmer has moved on. As a maintenance programmer for several decades, I can tell you that novel like comments do not help. But single letter variables that you used in your example do not help either. You are making the assumption that the next guy in line will know what you know the instant you are writing that line of code. (That next guy could be you 6 months later and at 3am all math is fuzzy logic.) There are coders and there are programmers. Programmers don’t ASS-U-ME!!!
private double SquareRootApproximation(square) {
rootApproximation = square / 2;
while ( abs( rootApproximation - (square / rootApproximation) ) tolerance ) {
rootApproximation = 0.5 * ( rootApproximation + (square / rootApproximation) );
}
return rootApproximation;
}
System.out.println( r = + SquareRootApproximation(r) );
Jeff, I have lost the last little bit of respect I had for you with this post. 
Seriously, though, I do find short what are we trying to accomplish here header comments helpful. Note that your refactored example no longer conveys the fact that it’s doing a Newton-Raphson approximation. Maybe that’s not a big deal there, but there are other situations where a fact like that would be good to know.
I like the goal of code blocks to be commented, so what in the sense of what are we trying to accomplish instead of what are we doing (which you correctly say should usually be understandable from the code itself).
Reminds me of one of our junior developers here. Her manager told her to comment a lot, so she does things like:
//Get the http session.
HttpSession session = request.getSession();
Which is utterly useless and just clutters the source files.
You just beat me to it.
Good method naming is great for people calling your code. For people actually maintaining your code, all naming is important. Method, variable, class, etc names should all be descriptive.
If there isn’t a clear name for an entity, there’s a very good chance that it shouldn’t exist in the first place.
One good example is loop counters. How many times have you seen for(int i = 0; i some_number; i++), when there is actually a meaning to the loop counter, such as an array index, or something_count?
By all means, keep code terse, but not to the point of obfuscation. FFS, a couple bytes of extra code for clarity is great value.
try writing some readable assembler code without comments… good luck with that. 
good post. i am often guilty of explaining in too much detail how something works in comments, whilst leaving other things uncommented altogether when they really need a good comment…
I still put some comments in my code, but I do make my code descriptive. The comments are typically for me, as more of a reminder of what I was wanting to do when I start to stud out a new class or method. I’m starting to do that with the TODO comments, but learning how to code w/out having that option available, I just got in the habit of one line comments as a quick reminder to myself of what else I needed to to do.
I agree with Will. I have personally been in the situation where I was asked to add a feature to a program that I had written three years earlier. I thought I had a good idea in my head as to how the original source code ran, and foolishly answered that it would be easy. I had a pretty good idea how to do it. But then when I looked at the actual code (with no comments, and with variables named ‘x’ and ‘y’ etc.) it took much longer than I had predicted just to find the right place to modify the code. FWIW, once I figured out where to modify the code, the actual modification was as easy as I thought. If only I hadn’t used up more than my allotted time for making the modification just figuring out my own code. BTW, this wasn’t even at 3 AM.
I have worked on teams where EVERY new line you write needs to have a comment (and the version control nazi/supervisor would nag you to death if you didn’t). That certainly doesn’t help anyone. If I write a function called ClientAuthNumber(client_id) I don’t think I should need to add // returns client authorization number based on client id or a = b + c; // a equals the sum of b and c …but I guess there are those who disagree.
On the other hand (and just as important), my team is now working on a huge application written by another company which we have to manage and there is hardly a line of code on anything. It seems for about a 2 year period from 2005-2007, they usually added just who updated it and when…not why it was added or if it affects anything else.
IMO, there is nothing harder to read than code that has 2 lines of comments before every line of code. If it is that hard to understand without EXCESS commenting, maybe it wasn’t well-written to begin with…
Wow, Jeff is really on a roll here. Code and comments are bad!
I guess I never realized that Coding Horror was actually about coding badly. Comments are not bad, BAD comments are bad. Just like code isn’t bad, but bad code is bad.
I’m honestly having a hard time believing someone as supposedly intelligent as Jeff actually believes this crap. It looks to me as though Jeff has discovered if you post controversial stuff you’ll get more ad hits. Whatever, thats his prerogative but I’m not reading it anymore.
Comments are my friend. Sure I could write a big block of code and walk through it to see what is done, but isn’t it quicker to just read a sentence or two before it so that I know what it does?
In addition, if you code something wrong (not that I would do that, but maybe some other developer would), wouldn’t it be nice to have a comment that says what the code SHOULD do?
My favorite comment is when someone does this…
x = 2 // set variable x to 2.
Not that I’d ever use that, but it makes me laugh when I see it. And then die a little inside.
I totally agree with the article.
Alex: I think you’re correct for the first time through the loop, but after that it changes and converges on the result.
One of the most important things I use comments for is to explain what is not available from looking at the code. For example a requirement of a called procedure:
if (x 0) then AbortProgram(X is negative);
y := PerformSomeMagic(x);
May deserve the comment:
//PerformSomeMagic will give incorrect results if passed a negative parameter.
I think Jeff has made his point by using an over-the-top comment example. I also comment methods before writing them. But I’m a bit more succinct about it (VERA code in a HW verification test bench):
// After (possibly a series of) call(s) to
// set_field, this task is called to write
// the shadow_value to the physical DUT CSR.
virtual task commit_fields_t(integer access_method = CSR_DEFAULT_ACCESS);
In my last post, http://mjbiren.blogspot.com/2008/07/check-in-your-changes.html, I note that one of the things you need to do when checking in changes is to make sure the comments are still relevant. This becomes easier if the comment’s content is short and only about code intent. Code details always change, if you comment like you’re writing code - then changes always become twice as much work.
So in the end, I think I half agree with Jeff.
No use of regions in you code, no comments, what’s next? Shall we say no to line breaks. Visual Basic you need them, but C#? It’s just a waste of space not to be using every pixel of your screen for conveying information. Why should I have to use my mouse wheel to scroll up and down someone else’s code when they could have fitted it into one small area. This would allow me to have many classes open on my screen without having to alt-tab between them. So efficient is this way of code that before reading any code I run a script to remove all white space from it and check it back in. Another advantage to this style of coding; I can use a USB photo frame for displaying some of favorite classes of code. Code Analysis can now include looking for secret Da Vinci Code messages. The fate of the world is in your hands if only you would advocate proper coding standards. Come on Scott the world needs just one more controversial coding practice to save it.
In a perfect world our comments would write the code.
And then your subroutine fails because t is undefined.
I dunno, I would still appreciate a one-liner about which approximation algorithm was being used. Numerical methods isn’t my strong point.
(@Will: The use of short variable names in the refactored function is fine; it’s a math algorithm and you need to be familiar with the algorithm to get it anyway; the long variable names doesn’t help there.)
In our organization (or the part I’m in, anyway), good practices like commenting code have not been paramount. I’m working to change that, including a requirement in the group I lead that we comment our code. It doesn’t (and shouldn’t) be book length, but some helpful hints here and there, telling the next guy what was intended, is very helpful.