[Grace-core] Comment proposal

[Andrew P Black]

On 4 Feb 2015, at 11:28 , James Noble <kjx at ecs.vuw.ac.nz> wrote:

> On 5/02/2015, at 07:56 am, Andrew P Black <andrew.p.black at gmail.com> wrote:
> 
>> I'm not aware of problems that our existing comment rules have caused.  If there are some, we should perhaps discuss these first, before proposing new restrictions.
> 
> so my take so far is:
> - we don't agree on what we think the existing comment rules mean

Yes, I agree.

> - we not sure if those rules should stay the same or not

Implied by the former: we need to clarify the wording so that at least we agree on what they mean.

> in particular, this bit:
> 
>> Comments are not treated as white- space. Each comment is conceptually attached to the smallest immediately preceding syntactic unit, except that comments following a blank line are attached to the largest immediately following syntactic unit.

> Michael is trying to build a parser that does the right thing, and that also will produce a canonical AST including comments.

Excellent!

> That will then make building formatters, refactorizers, etc easier (as per your work with Daniel Vainsencher!) 

Yes, that's the point of having the rules.
> 
> So the question is: how do those comments, exactly, get "attached" to the AST? 

We already answered that: they go in the AST node to which they are attached.  I think that the salient question is: what is the "syntactic unit" that our comment specification speaks of.

> thus questions like: 
> 
> var 
>  // comment here
>  x := 1 
> 
> which I certainly though would be legal, you implied should be illegal,

Yes, indeed.  I would phrase this as "is "var" a syntactic unit?   (I'm thinking not, it's just a part of a var declaration, but we coudl define syntactic unit so that it is.)  Is "var x" a syntactic unit — I think so.   And so is 1.  So a comment at the end of the line would go on the 1, not on the x, and if the statement is refactored so that the declarations and the initialization are split,  the comment would move with this 1.  This may indeed not be what is wanted — or maybe it is.

> Michael is keen on being illegal,
> Kim thought was legal and is "not excited about" banning, and I'm not sure what Tim thinks about this,
> or whoever else might weigh in on this list! 
> 
> 
> I think Michael's argument can be summarised as: 
>   "restricting comment locations 
>    makes attaching them to the AST easy (for the implementer) 
>    and predictable (for the programer)
>    and enforces good style (on the programmer)"

I agree with this entirely.  That's what the previous rules were designed to do, flawed as they may be.   What I'm questioning is the wholesale change in the meaning of comment placement that Michael's new rule imply, when most of them have not been problematic.  I predict that a wholesale to a new set of rules will introduce as many problems as it removes.

> that's the trouble with "minor cleanups" - there aren't many things that are actually minor. 

If you look with a powerful-enough lens, anything small becomes large.  In my experience, it's usually better to gradually things than to start over — for a while.   After 10 or 20 years , its probably time to start over.  

	Andrew