At 17:52 18/06/2002 -0500, Lawrence Lile wrote: >Here's a small addition to this (finally) serious list: > >The first line of my C or ASM file is a title, with the name of the file. > >Then the author, date, and purpose of the code > >Next (as James Mentioned) is a series of comments identifying each revision >level and why the revision was made and by whom, for instance: > >1 LL 1 Jun 2002 New Program >2 LL 2 Jun 2002 Found bug in rs232() function >3. RW 3 jun 2002 Fixed bug introduce in fixing the last bug >4. LL 4 jun 2002 Found another bug that was introduced in fixing >the second bug which fixed the first bug etc. etc. > >Each revision is saved in a separate file, in case I need to refer to it >later. I save a revision each morning first thing before I work on any >code, and then every time I do anything that either 1. works or 2. took a >long time to code. Well, all of the above is nicely managed by CVS automatically: author, date, version history, etc. plus you can check out any version from any date, etc. If you don't already use CVS (or any other version control system) I recommend to have a look, even if it is only to keep track of changes in source code in a single machine. Thanks! G. >Then I always clearly identify all I/O points near the top of the file, and >keep this list up to date > >// PORTB >#byte PORTB = 0x06 >#define Relay 0 // Relay on RB0 etc. etc. > >ASM files are usually commented with Pseudocode as well as clear >descrtiptions of what is trying to be accomplished > >C files are more readable, so I just try to de-obfuscate the code a little. > >--Lawrence > >----- Original Message ----- >From: "Guillermo Rodriguez Garcia" >To: >Sent: Tuesday, June 18, 2002 5:44 PM >Subject: Re: [PIC]: coding style > > > > James, > > > > Thanks a lot! This is the kind of advice I was after :) > > > > At 11:05 18/06/2002 -0700, James Newton. Admin 3 wrote: > > >The wonderful thing about standards is that there are so many to choose > > >from... > > > > :)) > > > > >I personally try to use all lower case for keywords, Underscores in > > >variables, All uppercase for defines or constants. > > > > > >Type of variable as first part of variable name, Since labels are >variable > > >of type "address" I try to use "at" or "a" as the first letter of labels, > > >but they also denote the start of functions or procedures so sometimes I >use > > >"f" or "p" or even "s" or "sub." > > > > At the end I think I'm going to adopt the following: > > > > - only tabs, no spaces. 4-spaces per indentation level. > > > > - one-character extra indentation for "bit-skip"-like operations. > > > > - C-style all-lowercase names for variables, with underscores separating > > words: > > > > timestamp > > sigA_count > > sigA_time > > adc_ch1 > > adc_ch2 > > ... > > > > - Same for 'higher-level' labels (i.e. function names or entry points > > for high-level blocks) > > > > - Preceding underscore helps distinguish local labels within a function > > or block: > > > > _skip_hi > > [...] > > _skip_lo > > [...] > > > > - All uppercase for constants: > > > > SPI_PACKET_LEN > > PROTOCOL_ID > > PROTOCOL_VERSION > > > > - And of course all uppercase for PIC registers. > > > > > > >Actually, when I'm writing code for someone else, I try to find out what > > >language standards they follow. If the boss knows asm I try to get a look >at > > >his code, If he or she knows Pascal I use that style, if it's BASIC > > >(shudder) I use that style. I even define macros to make some of the more > > >obvious commands match the "language" I'm trying to look like. Macros are > > >great for making code easy to understand.... if the macros make sense. > > > > > >And as Olin will probably say, comments are the best coding style. I >don't > > >comment every single line, but I write the program in pseudo code >comments > > >first and then "compile" each comment line into the ASM code that does >what > > >the comment says. No more than a few lines of ASM per line of comments. >The > > >tricky part is not changing the ASM code without updating the comments. I > > >also keep a log of the design decisions at the start of the file with the > > >date and what we were thinking at that point. > > > > > > Very good advice, thanks! > > > > G. > > > > -- > > http://www.piclist.com hint: The PICList is archived three different > > ways. See http://www.piclist.com/#archives for details. > > > > > >-- >http://www.piclist.com hint: The PICList is archived three different >ways. See http://www.piclist.com/#archives for details. -- http://www.piclist.com#nomail Going offline? Don't AutoReply us! email listserv@mitvma.mit.edu with SET PICList DIGEST in the body