>While I follow your methods normally, once in the flow of writing
>I often fail to comment to the enth degree (unless writing asm that
>is) and end up having to come back a day or so later to finish off.
>I keep changing my mind over commenting, do I do it every line or
>only commenting when it is not absolutely obvious in the code. I
>try to make it that you never have to read the code to see what is
>going on you should be able to from reading the comments. As you can
>see I keep changing my mind.

Well, some of this relates to using sensible names in variable declaration.
If you use names like "foo" and "bar" then you have to explain  what these
mean in a comment, each time you use them. If you use names like
"time_of_day" then the line of code probably does not need a comment, the
comments at the beginning of the block should do, with the occasional
interspersed comments like "update hours here".

>I keep to high level languages for most of my coding and only code
>in asm for the interrupt routines and speed related issues.

Well fair enough, but somewhere along the line the program structure still
needs to be laid out, and the method I showed is just as valid for an HLL as
ASM.

>One trouble with the comments is the headers take more space than the code!

Maybe, but if that is what is necessary to explain how the code works then
so be it. You should have enough comments that you can come back to it some
time after not having dealt with it for a while, and be able to pick up
enough from the comments that you get no surprises when you need to alter
the code. This is why it is necessary to do copious comments when doing some
real tricky coding that uses sneaky tricks with flags or registers.

Include anything that might be a caveat if you wish to do something else on
a port later. One that caught me out was with the 16F877, using I2C. It is
documented that you cannot alter the TRIS register once the I2C port is up
and running, without possibly locking up the I2C port, even though it is
other bits that you are altering. This is the sort of "gotcha" that needs to
be documented with a comment in the port declaration section of the code.

I have subroutines that do things like send CR/LF to the serial port. The
comments in the header are probably twice the number of lines that are
occupied by the code, partly because the header is built around a standard
template. The code is self explanatory really, but the header helps to
identify where the subroutine is when scrolling through the code.

--
http://www.piclist.com hint: To leave the PICList
mailto:piclist-unsubscribe-request@mitvma.mit.edu