[Grace-core] Comment proposal

[Michael Homer]

On Thu, Feb 5, 2015 at 8:43 PM, Andrew P. Black <black at cs.pdx.edu> wrote:
>
> On 4 Feb 2015, at 16:40, Michael Homer <mwh at ecs.vuw.ac.nz> wrote:
>>>     • at the end of a line, (but not at the end of a continuation that is
>>> continued on the following line).
>>>          Such comments attach to the first declaration or expression on that
>>> line.
>>
>> Is this the same as "may appear where a semicolon could, and attaches
>> to the preceding statement or declaration", or is it "may appear at
>> the end of the first physical line of a continuation-line sequence,
>> and attaches to the whole sequence”?
>
>
> I meant to say "(but not at the end of a statement or expression that is
> continued on the following line).
> I did not take the time to formulate this precisely; it was an example of
> the kind of rule we might have,
> rather than a well-thought-out proposal for a pacific rule.
I was trying to tease apart the cases around something like this:
    var x := abc.def
        .xyz
Is the comment permitted at the end of the first line, the end of the
second, or neither? In any case it should be attached to the entire
declaration "var x := abc.def.xyz". At the end of the first line is a
machine parsing problem, at the end of the second is a human parsing
problem. "Neither" is fine: once you had a continuation line, you'd
have to use a prefix comment instead.

In general, I think that if an expression is so complicated that it
requires comments in the middle then that's a sign that you should
introduce some intermediate variables, so there should be no need to
attach them at anything below the statement level. Short in-line
comments on the line of (short) statements are basically fine, but
it's difficult to separate them from intermediate comments or the bad
in-line cases.

There is still the double-comment issue:
    // A comment
    var x := 4 // Another comment
It's awkward to have two comments for the same item without obvious
precedence between them, but probably more awkward to ban one only in
the presence of the other. Given that one works (and is necessary
elsewhere) the other seems redundant.

Finding the smallest number of necessary supported locations possible
should be the goal. Ideally, there would also be exactly one location
for the comment on any given piece of code. I think statement-level
comments attached to the following line gives the right granularity,
probably with parameter comments as well, but there could be other
cases added if they're really necessary.
-Michael