A pithy way to phrase the above might be:
If you understand what it does, and you know it works, then you don't need to rewrite it!
You need to document it so you don't have to bang your head against the wall next time you look at it. In my experience, the only time you need to go through rewriting code is if the offending code needs to be extended or fixed and that is made difficult or impossible by the sheer ugliness of it.
This I guess is a corrolary to if it ain't broke then don't fix it. That law is *especially* true in software, particularly in high reliability production environments (which is all I've ever worked on BTW). If it *is* broke then that is quite another matter.
A few other methods I've run across:
1. Modularize. Have one bit of code that does one job and have it do it for EVERY possible consumer of that sort of task. I'd rather have a if-tree of slightly different ways to accomplish a task than have to go back and fix each one.
2. Test, test, and when you're done, test some more. Plan to spend at least twice as much time testing as you do coding. It stinks and it sucks but that's the only way to come out with good code. Use automated tests to cut the boredom.
3. Write readable code. Comment. Avoid the elegant approach in favor of the simple approach whereever performance allows. You *will* have to fix every bit of code that you write at some point. It's a certainty.
| [reply] |
This I guess is a corrolary to if it ain't broke then don't fix it.
I would consider any code that's too complex to be understood without comments to be broken :-)
If you don't spend the time to make your code simpler it just gets more and more complex over time - until you eventually end up with a big ball of mud.
Don't accept the evils of code entropy! Continually refactor your code to make it as simple as possible. You'll be surprised how quickly it pays off.
| [reply] |
I would consider any code that's too complex to be understood without comments to be broken :-)
Exactly right (smileys not withstanding) — at least from the developer's point of view.
Not only do you run the danger of ending up with a
big ball of mud, but as a maintainer, you'll become
increasingly guilty of voodoo chicken coding.
XP sez: Refactor Mercilessly!
| [reply] |
After i've viewed and made sense of a piece of crappy code i will put comments inline and update/create offline documentation if I have the time.
... but only if I don't have the time to write some tests that demonstrate what the code does and refactor the code into something more comprehensible.
Because if I don't rewrite that code into something more comprehensible I'll regret it six months down the road when a couple of feature requests and bug fixes have caused my comments and offline documentation to become out-of-sync with the code again.
Sure as onions is onions.
| [reply] |