William Chops Westfield wrote:
>
> Surprisingly, one of the times that it is common NOT to comment very
> verbosely is when the algorithm used is in fact VERY complex.  In this
> case it's generally assumed that the code is documented extensively
> EXTERNALLY (like, in books, papers, patents, and so on.)  For example,
> I've never seen anyone attempt to extensively comment a routine that
> calculates CRCs (either bitwise or bytewise.)  Your program is NOT
> the place to explain why a series of shifts and xors ends up producing
> coefficients for a polynomial...
>
> BillW

Yes, No, and probably "Maybe"... hehe

At IBM we use to debug software with 600+ pages x 66 lines / page. All
the documentation was listed together with the code, just because the
code was regenerated twice a day... it would be impossible to keep an
external reference to what each small routine was doing.

Recently I finished a 16,000+ lines of code, I created a external text
file just for comments.  The code needed to be generated in 3 files,
using "include" function, because the DOS text editor couldn't stand a
650k file size... <g>... even so, it was a pain in the neck to keep
commenting in one file and changing code in another file.   I would love
to see a code editor that could do both functions at once...

I already have lots of troubles to keep track of what version is the
last one, with so many protection copies, backups, moving disks from one
computer to another and so on.  I am *not* that organized.  It was the
version I changed code in the office, or at the lab?, or the one I did
at my home last night? I changed it last night? or it was something
else?... arggg, too old!  brain is starting to fail.

The CRC routine is very simple, few lines of commented code do it
nicely, but try to do the same for a HDLC (IrDa) communication routine,
the commenting details take more space than the code itself, but it is a
must to be able to understand it latter.

Wagner.