What I have done when I inherit someone (no longer available) else's code is the following:
in reply to Large-scale code documentation
The IDE interfaces facilitate some of the searching for callers and callees. I am now investigating Eclipse with E.P.I.C.. This is free stuff. It takes a little disk space and installation effort, but is an elegant way of tieing complex projects together. It also has an CVS client built in.
- I print out all of the code with pr -f -l55 | lpr. Three hole punch the pages, put them in notebooks. The top of each page will have the filename and date, so you should not get these pages mixed up with others that you might create later.
- Get out several highlighters and mark the beginning of ever package and sub, using different colors. Then highlight with vertical indented arrows the nested loops and blocks, etc.
- Make sure that all of the code is in a source code control system so that if I screw up, I can go back.
- Then, I sit back down at the computer editing program (I prefer Emacs), and start writing comment lines.
- When I think that I understand the how and why of functions and section of code, I write the POD entry right above the beginning of that blocks. POD can be specified for specific interpretors, so you can do HTML specific image references if you wish. This can all be done in a later pass throught the code.