Re: Danger, danger Will Robinson (documenting code)

[Malkavian]

This is a bit of a current one for me:
A lot of what I'm currently doing is reverse engineering existing code. Some of this is Perl. Some of this is actually very nice perl with documentation and descriptions of callers, arguments etc.
However, most of the code I have to deal with is old C shell (some BASH or ZSH) or distinctly flakey Perl (worse than mine by far, and I'm no guru).
This latter stuff has no documentation, and, being coded by volunteers over time, the coders themselves had very little view of the big picture, have moved on, and been replaced by other volunteers who've hacked the scripts to do more what they think it should do.
Examples of behaviour are:
C shell script. Has no documentation of what should be passed to it as an argument (or agruments). The arguments are actually referenced in obscure parts of the script. Various variables are named correctly in parts of the scripts, but 're-used' to mean completely different things if certain conditions are met.
Many of the scripts run correctly only if run as a particular user in a particular directory with very specific arguments (i.e. having a path/name of something it doesn't expect. It still builds up names of intermediary files it expects to find from what you enter, can't find them, and tells you it can't find the original file you specified, rather than the file it's trying to find.
These are simple things to document (well, at least the expected arguments are easy, and little bits to say what each part of code does).
Personally, the code I end up 'signing off' has a header to say what is it, what it does, the arguments it takes and what the end result it produces is.
Each subroutine is documented as args in, purpose and return value.
Every time I change code that's "In production", I make a quick comment to say 'I changed this code because... on date whatever'..
Just a little documentation is a wonderful thing.

Malk