I would like to see a similar post about logging. Fellow programmers use logs as debugging tool… They keep the same debugging comments as operational logging comments when in reality they don’t mean much to the people operating the system.
I, for once, tend to agree with Jeff.
You can certainly take it too far, but given a choice between descriptive subroutine/variable names and comments, I’d pick the descriptive names.
Sometimes a coder don’t understand even a simple operation. I think comments are vital for a program 
re senior v junior programmers.
You’re way off. I find the juniors are the ones who blat out code without putting comments in, these are the ones who tend to think they know what they’re doing and commenting would just slow them down.
Senior devs tend to comment what they intend the code to do as they go along.
On the other hand, perhaps junior = poor, and senior = good would be better descriptions.
I find that adding a small description of what a method does in an xml comment block is more then sufficient. Anything more than that is just padding out your line count.
Nice post! Even as I myself am a Technical Writer, zillions of comments in code don’t make documentation necessarily better. It is QUALITY of comments, in my opinion, that are what really make a positive impact on the generated documentation.
Am I the only one who dislikes refactoring to the point where each function has a huge name and only a line or two of code? I also have to agree with the other poster who doesn’t like huge variable names. I think there’s lots of cases, especially in numerics and scientific coding where complex algorithms can’t be easily refactored into one-liners and well-placed comments are needed to make the algorithms comprehensible.
Totally agree that the old-school documentation blocks as shown at the top of your post are horrible, though.
Jeff, what the hell is ‘r’ ? 
Shouldn’t it be ‘root’, or even ‘squareRoot’?
And ‘t’ isn’t even defined here, but it needs a better name too.
I agree with the other commenters who suggest that you should still have a comment identifying that you are using the Newton-Raphson technique. Makes it easier for a maintenance programmer to identify the algorithm and look up its pros and cons.
How bad is the code which checks for orange? Must have some values stored in Octal.
Here is another one:
Identi-doc: Author tediously annotates each modification with their date/initials.
I don’t know how many times I’ve seen this! Please everyone give that one up.
The Gassy One on July 25, 2008 09:01 AM
Oh… this is needed for some programms for medical devices and code reviews. We have signed code for MR-Scanners.
Because you work with joel, you think you can give us the advice of the day (Don’t disable menu item) ? I mean, programming and one of your favourite book is all about subtility and heuristic, and not giving some rule you illustrate with a two line function.
This is blog trollism. Hopefully the link are there to provide us some content, and steve yegge’s post is great as usual. You have a great blog, but please, give it up a bit with your strong opinion, weakly held motto.
I hope you don’t do spartan programming + no comment, the result must be quite ugly
I ran across some old Basic code the other day that I understood absolutely perfectly. I understood everything that it was doing.
But I had no idea WHY anyone would do this or WHEN it happened or WHAT it was trying to accomplish in the big scheme of things. It was clear…but pointless.
It took me 1-2 hours to figure out the code but 2 weeks to figure out when it was used and why.
Even Jeff’s comment about SquareRootApproximation misses the point. As long as you tell me it’s a square root function (comment or method, don’t really care), I can test it fairly easily and I care very little which method is being used because I can easily replace (with return Math.Sqrt(n) it if it’s found to be wrong.
But why the HECK is Jeff rewriting Square Root anyway? Does Math.Sqrt() have a bug or something? Does one of the many easier alternatives of computing square roots not work?
I still have absolutely no idea why this was done, what to do if it has a bug in it, nothing… Everything Jeff made a huge deal about in the article is rather pointless when I come back to his code.
Huge comment block? Easily ignored with PgDn.
Comment or Method? Don’t care.
Using an enum parameter to avoid a comment? You’re an annoying dork, but I don’t care.
Not giving the how, why and when? Major issues when it breaks.
I’ll agree with Jeff on this one. Write the code to be as clear as possible. Use peer review to help. Comment on WHY and not WHAT.
I’ve worn out many a Page Down key by skipping over headers in files (my last company required them). Most of the time the WHAT didn’t match with the working code, so I acquired the habit of not reading them.
For those of you who have never seen too many comments, consider yourself lucky. I had one project where the developer put no comments in 30,000 lines of code. He was told to comment the code, so he wrote and AWK script to put comments on every line. The comment was usually one word, such as ‘yes’ for if (someCondition) and ‘no’ for else {}, and ‘oops’ for exception handlers. The code itself was pretty good for it’s time (1994), and when I asked an old co-worker about it, is still in use today.
private double SquareRootApproximation(n)
Great, now you’re paying function call overhead on each call for an algorithm that is usually used in places where it needs to be run often and fast. The comment would have been a much better choice.
Comments rapidly become out of date with refactoring, and with fellow programmers not updating it.
That is an excuse for sloppy and lazy programmers. If it hurts when we that, then maybe it’s time we figure out that we shouldn’t be doing that. I suggest a simple four step program:
First offense = verbal warning
Second offense = noted on performance review
Third offense = forfeit bonus
Fourth offense = termination
Harsh, you say? Far mor lenient than government or financial institutions’ penalties for not keeping your house in order, I say.
Also, why are you reading the code if you don’t know why or how you got there?
I take it you work in a rather sheltered environment. Ever have an emergency fix request for a project you never worked on dropped in your lap?
If you can’t tell what the code does without comments, the code isn’t done yet.
Have you ever considered the fact that the maintenance programmer is likely not going to be at the same level of experience and skill as you and is going to need some crutches?
Commenting code goes way beyond typing double slashes and telling little stories.
Jeff has demonstrated some great idea’s that go beyond what a beginner would.
Isolating a code fragment (probably re-usable at that) and giving it a meaningful name is a great first step.
Getting all of the FM (Funny Magic) numbers out is great too. Constants can be named to something meaningful to add context. I realize that the constants in this example are too simple to bother naming.
I am undecided about where to document the actual Newton-Raphson algorithm and will sit on the fence on this one.
Putting a type declaration on the argument list on the method call certainly alerts callers as to what algorithm is being used, but I still wonder if that should be encapsulated inside of the function itself.
Hard to answer without knowing the importance of the algorithm and why it was chosen instead of a standard library function.
Agree, i have no problem with naming stuff like GetWeekNumberStartingFromLastMondayOfPreviousYear(), with intellisense you only have to type 3-4 letters anyway.
But if you have to concat some strings with several calls to the method i try to come up with a shorter name.
– 8 – snip –
I had one project where the developer put no comments in 30,000 lines of code. […], and when I asked an old co-worker about it, is still in use today.
– 8 – snip –
That’s probably because no one dares to touch 30K lines of code without having a clue what it is supposed to do.
SCNR.
never, ever start with comments ??
I do it all the time for almost 20 years now. Worked pretty well so far.
Ok, I’m pedantic. Maybe the last line of the refactored code should pass n as the parameter, rather than r.
System.out.println( r = + SquareRootApproximation(n) );
I love the Refactor menu in eclipse - it saves problems like this.
John.
When it comes to comments I find I have a weak beliefs, weakly held methodology. Verbosity, lack thereof, algorithm references (eg Newton-Raphson), why vs how- I mean, any one of reasonable programming experience could argue any one of these, on either side, indefinitely. The only advice on commenting I ever hard that I really feel should be applied in all situations, is in the beginning of every oreilly book. If any of the previous rules makes the code less readable, throw [that rule] out.
Every rule you ever hear about good commenting is a guideline. There will be exceptions to that guideline. Pointing out exceptions to the guideline as proof that it’s not infallible (and implying that not infallible = bad guideline) is honestly kind of useless.