[Grace-core] Comment proposal

[Michael Homer]

On Wed, Feb 4, 2015 at 12:56 PM, Kim Bruce <kim at cs.pomona.edu> wrote:
> 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
The (An) issue with something like this is that you run out of space
and then write:
     thinList := myList.filter(no_punc)   // Remove punctuation that has no use
                                .toLower          // after this point
and canonicalise
, which in a language with semantic comments is clearly wrong, and to
allow it is to encourage bad style and bad comments.

In these nice examples it all looks straightforward, but the world
isn't nice and in reality argument lists will be long or split over
multiple lines. A comment at the end of that is no longer localised,
clear, or particularly helpful. There are occasions where it looks
like it might work, but it's not worth the complexity of supporting
those when putting the comment beforehand consistently works just as
well all the time and is stable to extensions, shifts, and
reorderings. A blanket rule of putting the comment before its target
across the board is easy to apply for the programmer and the reader.

If comments are going to mean something then we need to acknowledge
that they are different than in other languages and adjust
accordingly. It's an advantage, not a limitation.
-Michael