From: "Andrew P. Lentvorski, Jr." <[EMAIL PROTECTED]> On Mar 13, 2005, at 10:41 PM, Gabriel Sechan wrote:
It takes about 5 seconds more effort to define a constant and use that constant than it does to put magic numbers everywhere. The end result is more readable and more easily changed. You gain time by this, not lose it.
That may be true, but that is an easy example. Let me choose something more complex:
Accessing a file by name
Doing that in the general sense is a lot of code. It may, in fact, be more code than the original program. If I am on UNIX, I will probably just absorb the filename from a command argument and punt. However, that breaks:
1) Windows machines (how about that backslash?)
Actually, Windows works if you do take in the filename, it breaks when you hardcode and have the wrong slashes (assuming the user didn't type in the wrong slashes, in which case i will probably go into a very wierd named file in the current directory). Or you write a MyOpenFile function that reverses / and \ based on #if WIN32 and never look at it again.
2) Mac machines with case insensitive filenames
Unix is case insensitive too. So how is this a problem?
3) Most things requiring unicode
Ok, granted here. I do assume the filenames are english, typicly.
Shells do the deglobbing for you, unless you mean a user inputs the filename with a glob from a prompt, not the command line. In which case its his fault for being a moron, you write it to the file he specified, globs and all.4) Shells with various globbing conventions
\>
The comment didn't go obsolete. The code went obsolete. The comment stated exactly what the code did and why, so we could test against it and see if it was still needed.Comments don't become obsolete if you *gasp* update them.
Oh, please. Your interrupt delay is a great example of a comment that went obsolete even though the code did not change at all. So, whose responsibility was it to update that comment when the ASIC changed?
By the way, my latest what did they do that for- they added 100 microseconds to the interrupt length due to signal noise on a 3 year old asic. Please tell me how the hell I'm supposed to figure that out without a comment.
I really couldn't have come up with a better example of my point. Thank you.
Is that 100 microseconds still 100 microseconds on the current chip? Is the signal noise still present? What was the proof that adding the 100 microseconds solved the problem rather than hiding some other problem? Was it signed? Was it dated? That comment can become obsolete without any code changing.
Now imagine that code had just been in there with no comment. No idea why its there. Could I remove it? Sure- but it'd scare the hell out of me. I'd have to order full regression testing of the entire code base. Neither the testers or the managers like that. But changing something as important as that on this code would require it to have any certainty of the resulting code.
Now with the comment, I know why its there. I know the risk of removing it, and I know what I need to test against. I have much more confidence in the safety of the removal, and have a specifc problem I can test for to see if its still needed. Without the comment, that line of code remains forever, because noone is quite sure what it does and noone ever removes it. Worse, they likely hack elsewhere to make the numbers work with that addition. With the comment, its gone and the code becomes cleaner.
I can't trust the code or the comment. I will have to check it myself.
Ever hear the phrase "trust, but verify"? You have to verify it with or withotu a comment, but the comment gives you a good starting point. Its more than you have without it.
That having been said, I will be grateful that there is a comment signaling that something weird was put in intentionally. However, my activation energy for adding a comment is *really* high. It normally has to be something very odd that bit me really hard or is likely to bite the next person really hard (your ASIC comment actually would pass my test since it was likely added in in response to a bug that required a lot of work to hunt down).My rule of thumb is much, much lower. Every function gets all inputs, outputs, and globals it touches documented in a function header. Blocks of logic get commented. WHile I don't comment every line (I agree thats useless, thats why we have code), if I spend 6 lines finding the smallest element of an array I'll put a comment at the top of the loop that says its what I'm doing. If its something I'm adding to fix an obscure and hard to find bug, it gets a much longer comment describing the bug, dated, and signed. More work? A little. But the next guy down the line can pick up where I left off pretty easily. Bugs can be found more easily because you know what I think I'm doing, and you can more easily check the code to see if what I'm actually doing mathes that. And high level problems are easier to find because you can see the algorithm through comments without getting bogged down in code. Its a win all the way around.
Gabe
-- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-list
