Re: [lmi] [lmi-commits] master 783f4dd 5/9: Consolidate and revise documentation

[Greg Chicares]

On 2018-04-05 20:39, Vadim Zeitlin wrote:
> On Thu, 5 Apr 2018 18:33:50 +0000 Greg Chicares <address@hidden> wrote:
[...]
> GC> Function comments often want to be long. Headers want to be terse, so that
> GC> the whole thing can be gotten at a glance.
[...]
>  In addition to being unachievable, I don't see why would we strive to make
> the headers terse -- at least any more so than any other file.

Let me clarify what I meant:
- Headers want to be terse, so the whole can be seen at a glance.
+ Class declarations want to be terse, so the whole can be seen at a glance.

> Maybe this
> would be a desirable consequence of other good practices, such as single
> responsibility principle and general modularity, but why should this be a
> goal on its own?

I see it as a crucial goal on its own. Polya's _How to Solve It_ can be
boiled down to just these seven words: "Can you see it at a glance?".
Maybe it would be better to say that deep understanding is to goal of
reading code, being able to see it all at a glance is a necessary
postcondition of real understanding, and a synopsis greatly facilitates
understanding. I want to stare at the minimalist kernel of the thing so
that I can perceive the interactions among its parts.

[...splitting a member function's documentation between separate header
and implementation files...]

> GC> Comparing all the declarations in either set would require moving my 
> fingers
> GC> rather than just my eyes. So that idea doesn't work.
> 
>  As above, I recommend opening (the same) file in 2 splits.

I have a 25x99 editor screen, so:
 - two 12 x 99 windows don't show enough lines; and
 - two 25 x 49 windows don't show enough columns.
and vim splits just aren't an option for me at all.

>  Can we find some compromise that would allow to address this problem or do
> you think that this is not a problem at all or a problem not worth
> addressing? To be honest, I don't have any completely satisfactory
> suggestions, but I do have one which might be acceptable to you and would
> improve things significantly, even if it's not perfect: what if we extended
> the class comment -- which doesn't seem to be target to any constraints on
> its length for some reason -- to describe the interface/contracts of its
> member functions?

Okay, I've tried to do that for class wx_table_generator::column_info
in commit c9f958f6cb904.

Every time I open 'wx_table_generator.cpp' I go back to this nested class
to refresh my still-evolving understanding. Earlier today I found myself
copying and pasting this into a separate file of working notes:

// - is_hidden()
// - is_centered()
// - needs_clipping()
// - is_variable_width()

in an attempt to create a synopsis. But that list is hard to understand
without seeing the (trivial) implementations of those accessors, so I
was going to extract those and paste them into my notes in the hope that
I'd be able to get the whole thing at a glance. That's when I realized
that instead of writing external documentation to help me understand the
class declaration, I could just make the class declaration easier for me
to understand.

Earlier, you had said...

> I.e. for me there is always one comment describing the function interface
> from a public, external point of view and 0 to N comments inside its body
> for things that are important internally but don't affect the public
> contract.

...so, for example, here:

    // Return true if this column should be centered, rather than
    // left-aligned. Notice that this is ignored for globally right-aligned
    // tables.
    bool is_centered() const
    {
        // Fixed width columns are centered by default, variable width ones
        // are not as long strings look better with the default left
        // alignment.
        return !is_variable_width_;
    }

I extracted the comments into an organized block above the class declaration,
placing the subordinate comment in square brackets in order to preserve the
distinction you had made. (Square brackets were just the first idea that
occurred to me; I don't mind if the structure of commentary is expressed in
some other way.)

Maybe this isn't a good example--I don't really see a separation of interface
from implementation in those two comments. But I already understand what the
comments say. What I don't understand is how the various concepts in this
class work together to form a single whole.

Distilling the class definition down this way now leads me to a question
that I hadn't thought to ask before:

    bool is_variable_width() const {return  is_variable_width_;}
    bool needs_clipping()    const {return  is_variable_width_;}

Aren't VariableWidth and NeedsClipping two facets of a single concept?
AIUI, a column with this property has no predetermined width, expands to
occupy free space not wanted by other columns, and is clipped if that
expanded width is insufficient to show all its contents. Is there any
reason not to merge these two concepts into one?