Re: Inline Documentation, Part I

[Ed Blachman x4420 <edb -at- FAIRPORT -dot- HQ -dot- ILEAF -dot- COM>]

I should say upfront that I'm a programmer, that I believe strongly in
the value of inline documentation, and that I sometimes don't follow
through on that belief.  Notwithstanding my personal record in that
area, I think Gerard's discussion (or at least part I, which is all
I've seen so far) is well taken.  However, I can't resist quibbling...

>(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.

I think this is too optimistic.  I assume that people reading my code
should know the (computer) language the code is written in and the
(human) language my comments are written in.  But they may well be
unfamiliar with the application, or the code libraries that support
the application -- so it is very important to document inline what the
code is doing at a high level, the expected inputs and output to be
generated.

Sometimes I can be certain that there is higher-level documentation
available -- stuff that explains the purpose of the application or the
chief data structures.  But not always, especially at the beginning of
a project (when IMO it is most crucial to write inline doc).  The best
solution is to write enough conceptual doc to minimize the bulk of the
inline stuff -- but sometimes the schedule doesn't allow that.

After the basics are documented, then it is also important to document
the items listed in (3) -- but the basics come first.

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

In my experience, when a programmer writes inline doc, that doc
strongly reflects the programmer's own personality.  People who are
verbose in conversation write verbose comments, and so on.  Asking
someone to change the style of the inline doc they write is like
asking them to change their speech patterns -- you can *ask*, but if
you do you should be aware that you're asking for something *hard*.

But what you're really talking about here is the usability of the
inline doc a programmer writes.  In that respect the best approach is
no different from trying to figure out whether anything else is
usable: test it.  Write it however seems best, then find another
programmer and see what that person thinks of it.  That's easy;
imagining (accurately) what readers will know is hard.

-- ed

Ed Blachman     edb -at- ileaf -dot- com   (or)    ...!uunet!leafusa!edb