Re: Documenting Code (was:Programming language vote - results)

[Robert Bernecky <bernecky@acm.org>]

Charles Lin wrote:

>     One problem with documenting code is that it is often at too fine
> a level.   That is, you document individual functions or classes, when
> what the user really wants is the overall structure of the code, as
> well as how this solution solves the problem.   Sometimes, one practically
> wants an overview manual of the code, including the approach to the
> solution, the data structures used, and their interactions.

Indeed.
Consider the usual situation: You get hired into a project with these
characteristics:
   - anyone who designed the original system has been laid off or
     has gone to greener pastures.
   - the system has been maintained for the last 3 years by apprentice
     programmers whose previous job was mechanic in a muffler shop.
   - part X of the system is chewing entire mainframes and growing
     at 15% per month.

The documentation you want to see (and rarely ever do) is:

- What is the INTENT of part X? E.g., in a matrix inversion
   routine, you want something of the form:
     "This function solves sparse linear systems.
       We don't use the built-in DOMINO primitive to do this,
        because the arrays have 250,000 rows and domino doesn't
        know from sparseness today."

- What is going to break if I change/replace/rewrite this?
   In APL, this is a pain to determine, because of APL's
   prehistoric dynamic scoping rules. You have to know
   everyone who calls you (if you use/set a variable that's
   global to you), and you have to know everyone you
   call (if you set or use any variable), because ALL of
   your variables are visible to everyone you call.

   My approach lately has been to feed the entire application
   into the APEX APL compiler, which determines this
   as part of the setup for a later data flow analysis phase.

   In a large system, it's hard because you end up with
       . Black-box subapplications that (for historical reasons
         of wee, tiny main memories) set global/semi-global
         variables. No, you do not have access to the source
         code for the black box.
       . huge function paging files that are either unavailable
         or undecypherable.
    The advent of code maintenance systems such as LOGOS
    help the latter, but not the former.

Bob