Danger, danger Will Robinson (documenting code)

[jepri]

I was just browsing the net (isn't that a common start to so many stories thesedays) when I came across something that seemed worth sharing here. It was on the page of a microchip site and was part of an article on assembly language coding. I scanned through it and was caught by the authors little sidetrack into comments on documentation.

Since this has been a hot topic at the monastery at various times I was intrigued to see the same comments being used in discussions on documenting assembler.

The thing that prompted me to bring it up here was my thought that (in my mind) these two languages (perl and asm) could hardly be further apart, but many of the points made seem to apply to documenting both. To my mind if there are similarities between two things that appear to be very different, then there is something to be learned. Plato is my hero.

Please post your own memories of horrible or wonderful code that you have dealt with, and don't worry if your points contradict each other (or someone else), since the author manages to compain both about too much documentation, and not enough (presumably not in the same code sample).

For myself, I have spoken every point on this list at least once, with the addition of:

The author had an appreciation of tacky science fiction that I (unwillingly) became familiar with.

Please read the authors experiences reproduced below and post your own memories of code that you considered poorly documented.

----------------

When was the last time you worked on someone else's assembly program? Were you able to work comfortably with the code and attending documentation, or did it leave you on the verge of a slanderous rampage? The complaints I have voiced most often (and loudly in an empty lab) are these:

1. This program does not have enough high-level documentation—it's all details.
2. This program has wasteful documentation of its simplest parts.
3. This program is packed with spaghetti code and interlocking loops.
4. There is not enough information here to even assemble the original source (makefiles, etc.), much less make changes.
5. The comments are written in a grammatically incorrect format, eliminating important words, such as verbs and articles, for brevity.
6. This programmer wasted his time on long-winded comments that are as extensive as the source code. Why shouldn't I just skip the comments and decipher the actual code?
7. This flowchart or state chart is out of date with reference to the current source.
8. (Add your favorite gripe here.)

____________________
Jeremy
I didn't believe in evil until I dated it.