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
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
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"
thing worse is having your boss
standing by your side waiting for your explanation of the design during this entire process...
"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."