Inline Documentation, Part I

[Vignes Gerard M <gmv0570 -at- UCS -dot- USL -dot- EDU>]

                        Inline Documentation, Part I

                        Defining the Audience

        Many programmers resent having to add inline comments to their code
        and, like beginning composition-students, fail to grasp some of the
        most essential concepts upon which excellent (and rewarding) writing
        is based.  One of those key concepts is that of audience: the "who?"
        and "why?" which dominates all literature, be it poetic or technical.

(1)     Who reads inline documentation (coding comments) anyway?

        Well, the audience is almost certainly:
        (a)     intelligent,
        (b)     experienced with computers and programming,
        (c)     and probably interested in performing one of:
                (i)     porting the code to a new platform,
                (ii)    fixing problems which may have been present all along,
                (iii)   or extending the functionality of the original code.

(2)     So... what do they already know about the code?

        It's a safe bet they already know:
        (a)     what the code is supposed to do from a user's perspective,
        (b)     what inputs are expected,
        (c)     and what output will be generated.

(3)     What do they need to know then???

        In order to perform the kinds of maintenance described in 1.c,
        the audience will need to know:
        (a)     how the code actually does what it is supposed to do,
        (b)     where it does whatever it does,
        (c)     and what assumptions were made that might not hold if:
                (i)     the platform were changed,
                (ii)    errors were still present in the code,
                (iii)   or the functionality were extended.

(4)     Can we converse with them like adults, or should we painstakingly
        describe *everything* to them, like children?

        (a)     Remember that the audience is almost certainly limited
                to experienced programmers and novices looking for new
                challenges, and they would not be digging around in the
                source code unless they were familiar with (or trying to
                become familiar with) the environment.
        (b)     Furthermore, programming environments (language + system)
                have at least one set of conventions and, unless one has been
                adhered to, the reader will have great difficulty following
                what is going on---even with the most effective inline
                documentation which has yet to be imagined.
        (c)     But no programmer approaches a maintenance task without some
                notion of what algorithms might have been used and how they
                could have been implemented, and these expectations must be
                used as the basis for determining which features to emphasize
                and which to gloss over.
        (d)     And it is these environmental-conventions plus an anticipation
                of what the reader may expect as a reasonable set of solutions
                that determines what should be spelled out and what can be
                silently assumed.

        In summary, don't waste the reader's time by elaborating on that
        which might have been expected, and don't create confusion by failing
        to adequately explain unusual or important features.

                                        Gerard Vignes
                                        University of Southwestern Louisiana
                                        USL P.O. Box 42709
                                        Lafayette, Louisiana  70504