Thanks, sundialsvc4, for a thought-provoking post. It got me thinking again about the general problem of documenting code, which is something I’ve been grappling with for a long time.

We all know the necessity of writing useful comments in one’s code, and the difficulty of keeping them up-to-date as the code develops. I suppose we’ve all experienced that syncing feeling that comes from reading comments that contradict the code they “clarify”. For example, I recently downloaded the perl-5.14.2 source code, just to have a look. Being a top-down kind of thinker, I began by looking for the main() function, and found the file perl.c which contains the following comment:

/* This file contains the top-level functions that are used to create,
+ use
 * and destroy a perl interpreter, plus the functions used by XS code 
+to
 * call back into perl. Note that it does not contain the actual main(
+)
 * function of the interpreter; that can be found in perlmain.c
 */
[download]

Great ... except that there is no file of that name in the distribution! I eventually tracked the main() I want down to perl-5.14.2/win32/runperl.c (at least, I think that’s the main() I want? :-/ ), so no major drama, but this does illustrate the syncing problem nicely. Perhaps a dynamic cross-referencing mechanism in POD could reduce this problem in Perl programmes? (Or does this already exist? I’ve only recently “discovered” POD, I don’t know it very well yet...)

A related, and, to my mind, far greater problem relates to documentation of design. As a rule, even a moderately-sized project begins with a design of some sort, and, if more than one programmer is going to be involved, this design must naturally be documented in some form so that it can be communicated from the designer(s) to the other programmer(s). Yet how often does this design documentation make its way into the code base repository? Perhaps management omit it from the code base to safeguard confidentiality? Or perhaps the design document(s), because they are stand-alone files and not part of the code, are omitted because they just don’t seem to “fit”? Whatever the reason, the result is too often a code base in which the (to my mind) most-important-documentation-of-all is missing. Sure, the design is implicit in the code; but, the whole point of documentation is to make the implicit explicit, right?

So, to answer the question:

what ought we have done, when writing the code the first time, to expedite the process of re-preparing ourselves to make proper changes to it, some (months|years) later?

I suggest:

• Document the design. Doesn’t need to be long and detailed; in fact, this is a case where less is probably more. Just a summary explaining what the major components of the programme are, how they fit together, and why the programme has been designed this way (and why possible alternatives were rejected). And include this document with the code base, perhaps by prepending it to the top-level code file, which is often quite short anyway.


• Perform a documentation review a short time (say, a week) after the code has been “completed”. Yes, this requires self-discipline. Yes, managers have more urgent priorities. But do it anyway, whenever you can, paying particular attention to syncing issues and cross-references, and your colleagues (or your future self) will likely thank you for it down the road.

Just my 2¢.

Regards,