[Grace-core] Comment proposal

[Kim Bruce]

> On Feb 7, 2015, at 9:36 PM, Andrew P. Black <black at cs.pdx.edu> wrote:
> 
> 
> I don’t think that the choice of comment symbol makes any difference to the users’s expectations.  Of course, I have absolutely no evidence for this.

	I have no strong feelings on the actual symbol.  I am beginning to think there may be some value to having two kinds of comments:  One that is extracted by tools and the other is ignored.  Both Java and Python have these, and it may solve these disputes about detailed comments that seem intended for the programmer modifying the code rather than the user of the code (and hence can be ignored by the tools).

> In contrast, since our only kind of comment is from // to end of line, it seems obvious that such comments apply to the code at the start of that line, rather than to the code on the next line.  This tells me that we should prefer Python-style method comments(immediately after rhe header) over JavaDoc style method comments (on lines before the method header).

	That’s not obvious to me.  I personally like comments before code and on the starting line for the code, though that may be mainly habit.  I like method comments to stand outside of the code for the method and to not be part of the block of code for the method (located it outside the “{…}”.

> Michael wrote: "Possibly a comment without other attachment at the top of a block can be attached to the block …  That is [a] case that's hard to handle otherwise.”  I think that’s correct (it would be weird to have such a comment at the end of the block), and it’s the reason for the existing rule that says that a comment following a blank line is attached to the largest following unit.
> Rules like "comments are permitted only where semicolons are permitted - and act like semicolons” are simple only to those who know about semicolons.  We have carefully designed Grace so that novice users don't have to know about semicolons.

	This is part of the difficulty of restricting comments — and why it may be easier to only restrict “special” comments that will be extracted by tools.

> James’ example
>> self compareTo (  other ) 
>>           ifSmaller { -1 }           // if I'm smaller, return -1 
>>           ifEqual    { 0 }             // if I'm equal, return zero
>>           ifLarger   { 1 }             // I'm biggest!! YAY! 
> can be dealt with as follows:
>> self compareTo (  other )  ifSmaller { -1       // if I'm smaller, return -1 
>>     }    ifEqual    { 0             // if I'm equal, return zero
>>     }    ifLarger   { 1              // I'm biggest!! YAY! 
>>     }
> but I have to say that I don’t like that very much.  We should be careful of designing a general rule around a specific example — anyone remember Zahn’s construct?   Even the most misguided language constructs have a few examples that meme them look good.
> 
> 
> 
> _______________________________________________
> Grace-core mailing list
> Grace-core at cecs.pdx.edu
> https://mailhost.cecs.pdx.edu/mailman/listinfo/grace-core

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailhost.cecs.pdx.edu/pipermail/grace-core/attachments/20150208/e2da402e/attachment.html>