[squeak-dev] Documentation

Chris Muller asqueaker at gmail.com
Sat Aug 18 19:23:52 UTC 2018


>> But do we REALLY want to bloat image memory with a bunch of
>> "documentation" that no one will ever read and will be out of date
>> within one release?  We can't keep our existing documentation (wiki,
>> etc.) updated, I'd suggest seeing if we can actually commit to
>> cleaning that up before harming the image with new kinds of
>> documentation.
>
> The thing is about a per package class is that it’s not separate and is easy to keep up to date.  If there’s good tool support (eg a help browser like system for organizing documentation & examples) then there’s incentive to keep it up to date.

That seems like it would be the case, but in my own practice of doing
it, my subclasses ended up as much out-of-date as various other class
and method comments throughout the system.  I think your VMMaker
example is illustrative of that it really boils down to the "economy"
of documentation.  Whenever we're writing documentation, we're not
only not writing or clarifying code, but  actually creating an
entirely new artifact that must be physically maintained in the future
-- "another mouth to feed".  I'm sure discipline is a factor too, but
I think this economy is a large reason why even in-image documentation
is always behind the code.

> And these things should be trivial too strip for deployment if one wants.

True, but it's not only about RAM though, but other dimensions of impact like
"reader fatigue".  Anytime documentation is dilute or repeats what's
already very obvious, it's value becomes immediately discounted by the
user.  They start skimming comments instead of seeing them as "gold
nuggets" of pure value.  Pretty soon, they've trained themselves to
ignore them entirely, and suddenly they're not getting maintained
either.

Documentation is and should be an art.  The goal is not
"documentation", but clarity for users.  When something is small or
simple, there is already a huge headstart on clarity, which is why
in-image documentation should only be very minimal and _additive_,
never duplicate.

Class comments, for example, should not list out
their instVars with descriptions that are either obvious or
could/should otherwise be found in the accessors.  Instead provide
only what's not obvious -- perhaps a brief high-level descriptions
that summarizes its responsibility and overall implementation in a
sentence or two.  It should "decorate" the code elements by enhancing
its readability, not replacing it.  Anything more quickly becomes
subtractive -- future maintenance, reader fatigue, RAM, etc.  It's a
balancing act.

Best,
  Chris


More information about the Squeak-dev mailing list