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?) 2) Mac machines with case insensitive filenames 3) Most things requiring unicode 4) Shells with various globbing conventions
Fixing all of that may be more work than writing the original program. If, however, the program takes off, I will go back and retrofit filename handling as required.
80% delivered now really is better than 100% delivered never and is often better than 90% delivered later.
If you're developing good abstractions, this pretty much occurs anyway. You end up with a few files full of UI and IO code, and a lot more files of application logic. If you're mixing app logic and the other calls without abstraction, you're going to get in big trouble sooner or later anyway. It becomes very hard to figure out what logic is effecting your output when its spread across 9 files, vs when its all done by calls into 1 interface.
I tend to agree with this, but you don't always know what abstractions you need up front. In addition, if you make code *too* malleable, it is hard to hold all of the different malleable dimensions in your head.
Never done maintenance coding, have you?
Sadly, that's almost the only thing I do when I touch an open-source program.
My most common thought when looking at some of the 10 year old code I work with on a daily basis is "What the fuck were they doing that for?" If they put in a comment, I *know* why they did it.
And, more often, I run down a rat hole because the code did something other than what the programmer *thought* it did. The only comment I trust is assert().
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.
The only proof of correctness will be to delete the weird code, recompile, and rerun the current system to see if it breaks.
I can't trust the code or the comment. I will have to check it myself.
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).
Floating point math routines often get comments. They also generally get a reference and a hyperlink to the section of IEEE 754 that is relevant. Subtle data structure implementations get comments with reference and hyperlink. If it doesn't warrant this level of detail, it probably doesn't get a comment.
However, the most common comment in my code is "FIXME: Too clever. Do not debug this, replace it with something cleaner <date> <name>." Unsurprisingly, when I go bug hunting, probably about 1 in 2 bugs will be in one of those sections. At that point, I beef up the unit tests and rip it out.
-a
-- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-list
