Danger, danger Will Robinson (documenting code)by jepri (Parson)
|on Mar 29, 2001 at 17:44 UTC||Need Help??|
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.
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: