Re: Large-scale code documentation

What I have done when I inherit someone (no longer available) else's code is the following:

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.

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.

perlcapt
-ben

Comment on Re: Large-scale code documentation

Replies are listed 'Best First'.
Re^2: Large-scale code documentation by jacques (Priest) on Nov 05, 2004 at 15:13 UTC
Thanks. I have already printed out some of the code and highlighted different areas. Like you, I enjoy having the code on paper (although that's a lot of paper). Why would having the code in a source code control system be vital? In addition to the volume print outs, I also save a copy of any files I am working on and then test my changes. I will also be the only person modifying the code... Are there any benefits of a code control system that I am missing?	[reply]
Re^3: Large-scale code documentation by perlcapt (Pilgrim) on Nov 05, 2004 at 21:21 UTC
A source code control system allows you to go back to previous versions and do comparsions of versions. This is important because it is not uncommon to break one thing while fixing another. The version comparisons help figure out how that might have happened. Secondly, source code control systems are an efficient storage method because they store only the changes to files rather than multiple copies of the files. Thirdly, despite the extra pain in the neck that CVS and similar systems are to administrate, they allow multiple copies of the code to be checked out (usually by different people). When the people commit their additions and revisions, the system looks to see if there are conflicts in the areas that have been worked on. It demands that the conflicts be resolved before a new version is released. Another benefit of all of these systems is that they enforce a certain discipline of documenting what you have worked on. Actually, I have found that documentation more useful for billing or job review than I have for benchmarking the progress of a job, which is its original intent. You may think that only you will be working on this code, and that may be very true. But, you 12 months from now, after working on some other branch of this project or some entirely different project, you will appreciate any structure and documention that exists. It will help you get back into the depths of the code elements. perlcapt -ben	[reply]