Re: [lmi] [lmi-commits] master 9b3d0f1: Write explicitly-defaulted [cd]tors inline, in class defn

[Greg Chicares]

On 2017-03-06 00:25, Vadim Zeitlin wrote:
> On Mon, 6 Mar 2017 00:04:11 +0000 Greg Chicares <address@hidden> wrote:

[...snip discussion of vertical alignment, on the desirability of which
we are unlikely to agree in this lifetime...]

> GC> so I think this is the One True Way:
> GC> 
> GC>     int                decimals_ {0};
> GC>     mce_rounding_style style_    {r_indeterminate};
> GC>     std::string        gloss_    {};
> 
>  Amen.

Hallelujah, we have reached agreement.

>  But just a question: where do the comments go in this style? I'm not
> always talented/concise enough to fit them on the same line, but putting
> them before the variable declaration risks destroying the vertical
> alignment. Does it (and their rarity, generally speaking, in lmi code) mean
> that comments for member declarations are discouraged?

Let's try it, with the example above.

    int                decimals_ {0};
+   // We might add a block comment here, to explain why an "indeterminate"
+   // initial value is wanted. Syntax highlighting makes it easy to parse
+   // this as a comment. But it does break up the flow, especially as it
+   // extends over multiple lines.
    mce_rounding_style style_    {r_indeterminate};
+   // And even this terse comment does break the flow, though not as badly.
    std::string        gloss_    {};

That doesn't seem ideal. Let's try something else:

    int                decimals_ {0};
+   mce_rounding_style style_    {r_indeterminate}; // See below.
    std::string        gloss_    {};

+   // Why is style_ initialized to r_indeterminate? Well, here's the
+   // reason. Blah blah blah.

That's better. If there isn't room for "see below", then there's
probably room for "v.i.", and anyone who doesn't know the Latin
abbreviation can find it easily with a search engine.

I used to favor short names, which required interleaved comments:

    // Inforce annual target premium.
    double InfAnnTgtPrem;
    // Inforce year-to-date gross premium.
    double InfYtdGrPrem;

but now I prefer names that explain themselves to anyone who's
familiar with the problem domain:

    double InforceAnnualTargetPremium;
    double InforceYtdGrossPremium;