[Grace-core] Comment proposal

[Kim Bruce]

I'm probably not as excited at restricting comments as the rest of you, though I agree there is an issue with making sure comments are attached to the right code.

I personally (as exemplified in the text examples) have no problem putting comments at the end of a complete statement:

     newList := myList.filter(f)    // throw away all ... in the list

Because of space reasons, this is especially helpful for published code (both in papers and texts).

I'm a little less excited about allowing them in the middle of complete statements, but there are some spots where I don't think it is awful:

    // throw away punctuation and change to lower case:
    thinList := myList.filter(no_punc)   // get rid of punctuation
                               .toLower             // & change to lower

Admittedly in the above case the comment before the line would be fine, but I don't see a huge problem with the comments at the end of lines.

Similarly for method definition, I could see
      aRect.at(pt+(30 at 20))                // start 30 to right of last and 20 below
                 size(width/2,height/2)     // make half as big as last
                 on(canvas)

Again, I wouldn't necessary fight for this, but it doesn't rub me the wrong way -- and at least in the above example, I like my commenting better than Michael's optional 4 or 5.

Kim



> On Feb 3, 2015, at 1:35 PM, Michael Homer <mwh at ecs.vuw.ac.nz> wrote:
> 
> My comment query got some response, including Andrew off-list
> indicating that his intention in writing that passage was that it
> would restrict the allowable placement of comments. I am proposing a
> simplification of the rule:
> 
> 1) A comment must occupy a complete physical line at statement level,
> up to indentation.
> 2) The comment is semantically attached to the statement or
> declaration on the following line.
> 3) Comments followed by blank lines or a closing brace are freestanding.
> 4) (Optionally) A comment may also appear on a complete line
> immediately before a part of a multi-part method name, and is attached
> to that part.
> 5) (Optionally) A comment may also appear on a complete line
> immediately before a parameter declaration, and is attached to that
> parameter.
> 6) A comment not conforming to the above is a syntax error.
> 
> The advantage of this approach is that there is one and only one
> location for the comment attached to any given node, and one and only
> one node that a given comment could be attached to, and it's very
> clear what they are. It makes the right thing to do stylistically be
> the only thing that works, like with indentation.
> 
> Overlaid rules about backwards and forwards attachment and syntactic
> units are non-obvious to the (particularly, novice) user and will lead
> to confusion about what is attached where and where they may be
> placed. Rare corner cases where comments can't be placed are
> unhelpful, but universal placement isn't compatible with affixing
> comments to their referents and drastically complicates the syntax.
> 
> This rule is always unambiguous, allows straightforward corrective
> error messages, and allows attaching comments to everything that
> should need documentation while prohibiting the perverse placements
> identified earlier.
> -Michael
> _______________________________________________
> Grace-core mailing list
> Grace-core at cecs.pdx.edu
> https://mailhost.cecs.pdx.edu/mailman/listinfo/grace-core