---- START NEW MESSAGE --- Received: from cherry.ease.lsoft.com [209.119.0.109] by dpmail10.doteasy.com with ESMTP (SMTPD32-8.05) id AE9F187101F6; Thu, 29 Jan 2004 11:27:27 -0800 Received: from PEAR.EASE.LSOFT.COM (209.119.0.19) by cherry.ease.lsoft.com (LSMTP for Digital Unix v1.1b) with SMTP id <6.00CC317D@cherry.ease.lsoft.com>; Thu, 29 Jan 2004 14:27:08 -0500 Received: from MITVMA.MIT.EDU by MITVMA.MIT.EDU (LISTSERV-TCP/IP release 1.8e) with spool id 9195 for PICLIST@MITVMA.MIT.EDU; Thu, 29 Jan 2004 14:27:00 -0500 Received: from MITVMA (NJE origin SMTP@MITVMA) by MITVMA.MIT.EDU (LMail V1.2d/1.8d) with BSMTP id 9053; Thu, 29 Jan 2004 14:25:48 -0500 Received: from pd2mo1so.prod.shaw.ca [24.71.223.10] by mitvma.mit.edu (IBM VM SMTP Level 430) via TCP with ESMTP ; Thu, 29 Jan 2004 14:25:44 EST X-Comment: mitvma.mit.edu: Mail was sent by pd2mo1so.prod.shaw.ca Received: from pd4mr1so.prod.shaw.ca (pd4mr1so-qfe3.prod.shaw.ca [10.0.141.212]) by l-daemon (iPlanet Messaging Server 5.2 HotFix 1.18 (built Jul 28 2003)) with ESMTP id <0HS90012KN17BU@l-daemon> for PICLIST@MITVMA.MIT.EDU; Thu, 29 Jan 2004 12:19:55 -0700 (MST) Received: from pn2ml4so.prod.shaw.ca (pn2ml4so-qfe0.prod.shaw.ca [10.0.121.148]) by l-daemon (iPlanet Messaging Server 5.2 HotFix 1.18 (built Jul 28 2003)) with ESMTP id <0HS900FFYN17RN@l-daemon> for PICLIST@MITVMA.MIT.EDU; Thu, 29 Jan 2004 12:19:55 -0700 (MST) Received: from MAIN ([24.85.68.251]) by l-daemon (iPlanet Messaging Server 5.2 HotFix 1.18 (built Jul 28 2003)) with SMTP id <0HS900H2FN16L8@l-daemon> for PICLIST@MITVMA.MIT.EDU; Thu, 29 Jan 2004 12:19:54 -0700 (MST) MIME-version: 1.0 X-MIMEOLE: Produced By Microsoft MimeOLE V6.00.2800.1165 X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2911.0) Content-type: text/plain; charset=iso-8859-1 Content-transfer-encoding: 7BIT Importance: Normal X-Priority: 3 (Normal) X-MSMail-priority: Normal Message-ID: Date: Thu, 29 Jan 2004 11:19:54 -0800 Reply-To: pic microcontroller discussion list Sender: pic microcontroller discussion list From: Bruce Partridge Subject: Re: [PIC:] Process To: PICLIST@MITVMA.MIT.EDU In-Reply-To: <32385.207.177.227.29.1075403104.squirrel@kauko.hallikainen.org> Precedence: list X-RCPT-TO: Status: U X-UIDL: 371856313 > Harold Hallikainen > > The other thing I like is COMMENTS! I type fast enough that the time to > add comments is minimal. The top of each subroutine or function describes > what the function does (the gazinta and the gazouta), what its side > effects are (ideally none, but you often mess with registers in assembly), > and the "design philosophy" (WHY is it done this way, URLs of references, > etc.). As I think about the process while writing a line of code, the > thought goes in a comment on that line. What does this line do? Why is it > here? These help me a lot when I go back a year later trying to add > features. > I first time I saw the "design philosophy" comments was only a couple of years ago. I was converting someone elses code and they had references to documents with chapter numbers to describe why they were doing things that way. Awesome! My code is now peppered with references to documents that explain what I was thinking. The documents are included in my version control system along with the code and the tool chain. --- Outgoing mail is certified Virus Free. Checked by AVG anti-virus system (http://www.grisoft.com). Version: 6.0.572 / Virus Database: 362 - Release Date: 1/27/2004 -- http://www.piclist.com hint: The PICList is archived three different ways. See http://www.piclist.com/#archives for details. .