What I have done when I inherit someone (no longer available) else's code is the following:
  1. 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.
  2. 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.
  3. Make sure that all of the code is in a source code control system so that if I screw up, I can go back.
  4. Then, I sit back down at the computer editing program (I prefer Emacs), and start writing comment lines.
  5. 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

In reply to Re: Large-scale code documentation by perlcapt
in thread Large-scale code documentation by jacques

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.