View Single Post
  #74   Spotlight this post!  
Unread 11-19-2002, 03:43 PM
kmcclary's Avatar
kmcclary kmcclary is offline
Founder:7 teams;Mentor:66/470/more
FRC #0470 (Grizzly Robotics)
Team Role: Engineer
 
Join Date: Aug 2001
Rookie Year: 1994
Location: Ann Arbor, MI
Posts: 495
kmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond reputekmcclary has a reputation beyond repute
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
__________________
Keith McClary - Organizer/Mentor/Sponsor, Ann Arbor MI area FIRST teams
ACTI - Automation Computer Technologies, Inc; Sponsoring FIRST teams since 2001!
MI Robot Club / GO-Tech Maker's Club / RepRap-Michigan / SEMICNC Club
"Certifiably Insane": Started SEVEN FRC teams & many robot clubs (so far)!
2002: 830 Rat Pack | 2003-5;14: 1015;1076 Pi Hi Samurai | 2005-6: 1549 Washtenuts/FireTraxx
2005-..: 1502 Technical Difficulties | 2006-..: FIRST Volunteer!
2009-..: 470 AlphaOmega/Grizzlies | WAFL | Sponsor & Floating Engineer for MI Dist 13 (Washtenaw Cnty)
2011: 3638 Tigertrons | 2013-..: 4395 ViBots | 2014-.. 66 Grizzlies | 2016: 6190 Will Er Run | 2017-.. 6101 Strange Quarks
Home Teams: 66 & 470 Grizzly Robotics
Local FIRST alumni @ or coming to Ann Arbor (UM/EMU/WCC/Cleary)? We Want YOU as a Mentor! Please email me for info!
Support CDF Reputation: If a post helped, thank 'em with rep points!
"It must be FRC build season when UR spouse & children become 'Action Items 8 & 9'..."
Reply With Quote