On 8/18/18, Chris Muller <asqueaker at gmail.com> wrote:
> 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.

+1
And there are a lot of classes where even a basic explanations of
instance variables which are not obvious are missing. So contributions
in the inbox are welcome.

Suggestion: Let's focus on a small group of packages. The ones which
are of current interest because of commits for other purposes. The
debugger at the moment for example.

--Hannes