[Grace-core] Comments (was Re: Putative Blog Posts)

[James Noble]

> How about a C in column 6?

:-) I am *so* tempted.

> Well, seriously even if I were to disagree with this, then we still  
> need rules that will enable us to prettyprint the program on a  
> screen.   I was thinking of a rule that says something like

right...

or as Kim says:

> I agree with most of what has been said, but (on comments) we will  
> still have faculty who insist the only "true" way of programming is  
> to use emacs or vi or whatever old-fashioned technology gets them  
> closer to the way they did it while in diapers (nappies?).  Thus we  
> need something that will work for them. Moreover, the lovely  
> development environments that we anticipate having will not be  
> around for at least a year or more.  Thus we need something that  
> will work for the next year as we circulate documents.

yep. and even with IDEs we still need a textual syntax that one can  
cut & paste
(and - great idea from Jan VItek - the "package syntax" - like Jars -  
should just be source code :-)
that is we follow javascript not java - web services, loadable beans,  
just send the source.
So if we want comments preseved in that form, we need a syntax in the  
input language
(because they are one and the same)

> 	a || (line remainder)  comment attaches the comment to the first  
> complete statement or expression that starts on the said line

or it attaches to the expression at the place where the line breaks?

> 	a |*   ...   *|  comment attaches to the next whole statement or  
> expression that precedes it.

yep - which is pretty much what we have, modulo syntax.

> I suspect that only by trying these out can we know if they work.     
> But notice that neither form works for method comments, which are  
> often used to describe the  action of a method; as such they need to  
> refer to the parameters and results of the method.  So the comment  
> needs to be positioned where the parameters and results are in scope  
> — _inside_ the method, not before or after.

> Perhaps the best solution to this would be to provide for method  
> comments in the syntax; we already have pre- and post-conditions.

Sure. And then we need a form for class comments, package comments...

Or we could tweak the /* and // rules and just say:
  comments inside expressions attach at the point they are
  comments at the top level attach to the *next*

And I think that "next" is the question of style - it's what JavaDoc  
(and now everything-else-doc does)
whereas I think Andrew prefers a "comment after first line of defn"  
style.

should we also go like Haskell and have a literate grace syntax?
or at least hint towards one?

And do we want to commit to // /* *?  or || |* *| or something else?

So I guess the question for today is:
  do we make these decisions now, tweak the text & post the blog
    (my bit on source code above, decide on syntax, decide on  
convention)
OR
  do we cut comments out of here, into a new proto-post?
     (where we can address those three questions at leisure)

James