@stephen
I think that’s a pretty good approach, the only problem would be that you might end up cluttering up the code with loads of generic to specific calls. Certainly, I can’t see any way in which it could be misunderstood.
See, your comment did get read.
PS It would have been better to find real code that used an approximate method because it was looking for performance enhancement over a traditional Math.Sqrt. At least it will shut people since most punters probably can’t do better than the Quake Source code.
e.g. Quake’s Fast Inverse Square Root
One explanation: http://betterexplained.com/articles/understanding-quakes-fast-inverse-square-root/
float InvSqrt(float x){
float xhalf = 0.5f * x;
int i = (int)x;
i = 0x5f3759d5 - (i 1);
x = (float)i;
x = x*(1.5f - xhalfxx);
return x;
}
Since you don’t require comments, I deleted them.
@Anonymous
Code routinely gets thrown away because it doesn’t contain any comments, and only the original programmers know what it does.
Especially when you look at brain-damaged stream-of-consciousness code that lacks any structure or abstraction, you get cravings for comments.
But are you convinced that comments will help under those circumstances? Surely they just become part of the chaos, rather than a mitigation of it.
@tricky
Looking at the article, it looks like the comments don’t help with understanding.
// store floating-point bits in integer
// initial guess for Newton’s method
// convert new bits into float
// One round of Newton’s method
You could probably match these to the lines, even if I mixed them up. All they do is tell you exactly what each line is doing, which is pretty obvious from the lines themselves (int i = (int)x; // store floating-point bits in integer is ugly as hell, but it’s not actually unclear).
The article itself proves that it doesn’t actually explain to you WHY that approach works/was chosen, or if there are any potential algorithm breakers.
I have to agree with one of the arlier posters that this might be trying to hard to drive traffic to the site. The originaly comment you posted, aside from the exaggerated nonsense about SSN and Mother’s Maiden Name was pretty reasonable. The comment explains what approximation algorithm is being used.
Comments are not a crutch. I’ve listened to you several times talk about how Intellisense is a crutch for you and I agree Intellisense can be a serious crutch for many but surely comments are not. If all you write are weak CRUD applications and your most complicated code resembles txtCustomerFirstName.Text = CurrentCustomer.FirstName then perhaps you don’t need comments at all but if you’re a real programmer then they can be very helpful.
I disagree (partially) with your comment-removing refactoring of the Newton-Ralphson sqrt(x). You’ve lost the tidbit that this function is well-known and named (Newton-Ralphson). Particularly for numerical algorithms or implementations of other named constructs/algorithms, it’s incredibly important to record the name of the construct in the code in order to communicate to maintenance programmers. It’s not always just an issue of the code being legible.
Jeff:
this should have been titled intention revelaing names. been around forever - the XP series of books beats on this topic to death.
I have to agree. If you find yourself commenting something, this is usually a sign that the variable or method or class (whatever it is your commenting) should be renamed to better explain what is going on. Comments are rarely kept up to date and therefore become useless and misleading.
@Tom - the ‘I deleted the comments’ was just me being snarky. -1 for sarcasm.
You’re correct that the comments that were added don’t add much, except to a non-c programmer, as they’re only explaining the how, not the why. Quick, someone convert it to language {Ruby/Perl/Python/Jasmine/Chocolate} and we can get this post well over 400 as we all bicker some more. [Drat - sarcasm again.]
Oh, and those comments aren’t the comments from the source, they were added by the author of the linked article.
It was just a random article. Here’s another on the same topic: http://www.beyond3d.com/content/articles/8/
For those too lazy to read,
// a 1 iteration Newton method with a good first guess; utilises knowledge of x86 hardware and float memory layout.
Hm, you should still have a comment in that code snippet stating it uses Newton-Raphson approximation, IMHO.
I’ll ditto this, and note that the second example doesn’t have a function name at all, so it’s a bit of a cheat to say that the third example is best (since the 2nd is obviously a function as well). Comments should be used to give notes on implementation details that aren’t obvious from the code.
I’ve never even heard of the Newton-whatever approximation, so there’s no way that I’d be able to reverse engineer that from looking at the code.
When showing examples of the right way to write code, the author should write code that does not have bugs that can cause crashes.
The example code throws an exception when the input is zero.
Thanks VERY much for this article.
I recently saw the best redundant comment ever in aMSN’s source code:
// Include the header file
#include webcamsn.h
#include kidhash.h
Me and my friends all had a good laugh at that.
@Tom:
But are you convinced that comments will help under those circumstances? Surely they just become part of the chaos, rather than a mitigation of it.
My whole point was that of course, when the code is commented well enough, then it is possible to keep using it, despite all the flaws it might have. If bugs are documented, they can be eliminated later on. If there’s bad structure in an application, and it’s documented, then it can be changed later on. Good comments in code help companies protect their investment in the source code.
However, many companies feel that commenting source code would encourage people to steal their IP. But that’s not very reasonable. It’s better to employ proper security measures and have properly documented code, than a mess of undocumented code (like it’s most often the case) that somebody might manage to sneak out of their office. The cost of wasted time trying to understand an undocumented mess of code by far exceeds the cost of security measures.
Most bugs and wasted efforts (busted deadlines, accumulation of problems and sheer impossibilities and infeasibilities) arise only out of undocumented code.
Comprehensive manual pages should exist for every single API function in a corporate software project.
Often, a bad or outdated documentation is much better than no documentation at all. Of course, continuously maintained documentation is even better.
I think you would want an execption to be thrown for something like that, not just return a zero…
Good article, point well made. Much better than that normalization post anyway! 
Vinzent Hoefler wrote on July 25, 2008:
– 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.
Not true. It started at 30K lines, and when I left was ~700K lines, with about 30 changes/enhancements released twice a month. It had gone through several refactoring of various sections of code (the database access was started with Oracle 6, and was refactored for 9i). Several other sections were refactored as well. I added extensive continuous integration testing, regression testing, and enforced code standards.
I get scared by people who say code isn’t as clear as english. I get this image in my mind of someone trying to write a novel in a foreign language they are not fluent with. Which, of course, is the case.
Now, a particular computer language might not be particularly good about expressing certain concept – case in point, the why of code. While ‘($phone) = $input =~ /(\d{3}-\d{4}/;’ might not require any comment – particularly if the content of $input were already described elsewhere, code doing the same thing on a language without a regex library quite likely would need some comments.
Still, if you can’t read the code fluently, you are not fluent in that language. The consequences of writing code in it, then, are about the same as for human languages – examples of which abound in the web. In fact, I have stored right here a document in english written by a chinese speaker not fluent in english which will serve as the basis for some code integrating their hardware into our business. I wish I could post attachments. 
Once you ARE fluent, deciding what the code is pretty simple: what is not being said by the code and what the code is worse at saying than english.
I’d try to avoid describing what the code is doing at all costs. If you do that, two things may happen:
-
The code is incorrect, and you’ll never catch the bug, because the comment told your brain what to expect. I have seen countless times people wasting hours and days to find a bug in 10 lines of code, only to have someone who doesn’t know what the code does find it instantly.
-
The code is changed, the comment is not. Maintainer’s nightmare ensues.
What!!!
Here’s what I think… If you are writing maintainable code that more than one person will be working with.
At the very least:
There should be a header comment that briefly describes the purpose of the method, who wrote it, and when. Then, each block of code should have a brief comment describing what it does. You should not have to look at 1 single line of code in order to find out what the goal of the method is, and the steps taken to achieve that goal.
The comments should tell the whole story as succinctly as possible. This way, someone can:
- Read through the comments to very quickly find out what the method does.
- Read through the code to understand all the detail.
If you just want to use the code and not necessarily fully understand and/or modify it, step 1 is a time saver. If you do need to fully understand and/or modify the code, step 1 may help you load the code into your head a little faster (particularly if the code isn’t written very well, and/or it is written in a style very different from your own).
And if you want maintainable code, of course you have to maintain the comments as the code changes.
- The code is changed, the comment is not. Maintainer’s nightmare ensues.
Comments MAY become out of date so therefore they should never be used… huh?
If you are commenting correctly then your comments should never need to change. They will describe what the code, function, etc does - which regardless of what is inside.