Quote:
Originally posted by Melancholy
Not quite engineering, and not quite a slogan, but my Computer Science teacher said this on the first day of class.
"The purpose of commenting is that if you get fired, or hit by a bus, someone else can finish your program!"
|
Actually that's not quite true... Try this version:
"The purpose of documentation is so that
you know what the heck
you were thinking when
you are
forced pick it up again a year or more later to either fix or upgrade it!"
Trust me, in industry if you aren't meticulous in your commenting, it can come back to haunt
you, sometimes
years later.
It's more than slightly embarrassing to be staring at your
own design two years later trying to get to where your
own head was at 3 AM that fateful "night before deadline" when you, cranked up on caffeine and desperately trying to get the darn thing out the door had some epiphany of insight. You can even remember thinking "Oh heck, this is
really cool, non-obvious, it works, and (fateful last words)
I'll just get around to documenting it sometime next week when I have "more time"...
The
only thing worse is having your
boss standing by your side waiting for your explanation of the design during this entire process...
SO...
"Document it like you know you're going to die next week, yet still care about it surviving."
Or, another point of view:
"Design and document it so OTHERS can understand it later, or you'll be passed over for promotion because now you're the ONLY person in the company ABLE to maintain it."
- Keith