in reply to Crash Course in POD
Single point of documentation
Remember that single text documents tend to vanish leaving the new maintainer/developer unaware of all the hassle you went though. I'd write the POD into all the scripts and then copy the useful bits into a separate file. It's more work, but it'll be more useful to the next coder.
Documenting a large project
As to your last question. DON'T TOUCH THE CODE! Yes, documenting is a pain, and boring and I'm sure you can see 1001 ways to make the code a little clearer but if you're not being paid to fix the code and it's in production, don't touch it. It works (presumably), leave it alone.
Just go in, test away, work out what it does, try to guess how it does it, and document what you can understand. It's (probably) okay to put stuff like:
but remember what you're being paid to do. Adding documentation to a program should never alter it's functionality. (Well, unless you're playing with Damian's selfgol).##### Warning: through inspection, it appears that the ##### following code may fail under these circumstances: # A) ..... # B) ..... # C) ..... ##### A possible solution is in the following (untested) ##### code: # ......... # .........
If you feel that something really ought to be changed, write it down and bring it up with your supervisor after the documentation project has been completed. Don't allow yourself to be pressured into making functional changes at the same time as you're making formatting/documentation changes. Something will go wrong and your documentation will get blamed.
Oh, and use CVS. Or some other revision control system. And check your changes in regularly, although probably on a code branch and not directly into the main tree.
Lastly:
Good luck!
Hope it helps.
jarich
|
|---|
| Replies are listed 'Best First'. | |
|---|---|
|
Re: Re: Crash Course in POD
by jens (Pilgrim) on Sep 25, 2002 at 02:40 UTC | |
by Sweeper (Pilgrim) on Sep 25, 2002 at 05:44 UTC |