I agree with both Olin and Scott regarding the level of documentation that should be present in both C and ASM programs. There should be an overall description of what the chunk of code is doing and there should also be line by line comments as necessary to help clarify what each part of the code is doing (especially in ASM). For my money, I would always rather have too many comments than not enough. Too many "guru's" out there think their code is so "self-documenting" that they are blind to the fact that no one else can initially understand it without a careful perusal of each line of code. -----Original Message----- From: Olin Lathrop [mailto:olin_piclist@EMBEDINC.COM] Sent: Thursday, March 08, 2001 5:55 AM To: PICLIST@MITVMA.MIT.EDU Subject: Re: [PIC]: Code Commenting, was: LCD problems revisited > clrf FSR ; Output the Message > OutLoop > movf FSR, w ; Get the Offset to Output > incf FSR > call Message > iorlw 0 ; At the End of the Message? > btfsc STATUS, Z > goto Loop ; Yes - Equal to Zero > call SendCHAR ; Output the ASCII Character > goto OutLoop > > ... > > ; Subroutines > Message ; Message to Output > addwf PCL ; Output the Characters > dt "Hello", 0 > > ... > > This brings up the question, how should code be "properly" documented? > Personally, I prefer minimal comments so that the operation of the code can > be seen easily without being distracted by comments. Comments are there to help, not distract. If everything is properly and consistantly formatted then they are not "in the way" if you prefer to ignore them. To facilitate this, I consistantly use column 10 for opcodes, 18 for parameters, and 30 for comments. I admit I haven't found a good way to deal with assembly directives. > So, the overall question is, what is the *best* way of writing code to show > concepts to others? I am very interested in this topic (and I have very > strong opinions on what is the best way to write/document/test code). Since you asked, here is how I would write and format this code: ; ; Write the message to the display. ; clrf fsr ;init message index outloop unbank ;back here each new message character movf fsr, w ;get the index for this character incf fsr ;increment the index for next time mcallr message, reg0 ;get the indexed message char in REG0 movf reg0 ;set Z if this char is null terminator skip_nz ;got valid message char, not terminator ? goto loop ;done writing the message gcall sendchar ;send char in REG0 to the display goto outloop ;back to do next message character ; ;******************** ; ; Local subroutine MESSAGE ; ; Return the indexed message character in W. The 0-N character ; index is in FSR, which is preserved. ; message locsub, noregs movlw low msg ;get low byte of table start address addwf fsr, w ;make table entry address low byte skip_ncarr ;propagate carry to high address byte incf pclath movwf pcl ;jump the the selected table entry msg dt "Hello" ;the message string to send dt 0 ;string terminator This isn't exactly the same code you wrote. I modified it slightly to fit the way I write PIC code, which includes my bank switching and subroutine linkage conventions. I made the assumption that this code was neither speed critical nor extremely tight on space (as is the case with 95% or more of all code). It is therefore far more important to make it robust and maintainable than super fast and small. For example, 256 word program memory boundaries can now be ignored, which was not the case for your code. Someone can come by in two years and add code above this snippet without having to worry. The only restriction is that all this code be on the same code page. I use linker sections to guarantee that all code within a module is on the same page. If I was writing this from scratch, I would have used general table fetching subroutines, but it would have been messy to include the source for them here. I haven't tried to assemble this snippet above, so it may contain typos, etc. All the macros, general registers, and subroutine linkage conventions I used above are defined in file STD.INS.ASPIC which can be found at http://www.embedinc.com/pic. And yes, I really do write all my code with this same general style and level of commenting. ***************************************************************** Olin Lathrop, embedded systems consultant in Devens Massachusetts (978) 772-3129, olin@embedinc.com, http://www.embedinc.com -- http://www.piclist.com hint: PICList Posts must start with ONE topic: [PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads -- http://www.piclist.com hint: PICList Posts must start with ONE topic: [PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads