[Grace-core] Comment proposal

[Kim Bruce]

Whatever rules we have for attachment are going to be more complex than novices are going to be able to handle.  I suspect that is part of why javadoc doesn't even attempt to handle most comments.  Instead they focus on particular stylized comments that do have a clear referent and then allow others wherever people want.

That is one option for us, but I suspect it is easier for us to have just one kind of comment and understand that some are going to be placed inappropriately by tools.  Much of the time that won't have many consequences and when it does, it should be relatively easy for students to see how to move them so they are attached properly.

Our general strategy in teaching Java has always been not to worry about javadoc comments in the intro course (or at least until well into the intro) and then make sure students know how to do the right thing by the beginning of the second course.  I suspect that is a strategy that will continue to be convenient for Grace.

We could even think about a dialect "strictComments" or "attachedComments" that is more restrictive than the general, less restrictive, rules.

Kim



> On Feb 5, 2015, at 12:58 AM, Michael Homer <mwh at ecs.vuw.ac.nz> wrote:
> 
> On Thu, Feb 5, 2015 at 9:26 PM, Kim Bruce <kim at cs.pomona.edu> wrote:
>> Whatever we do I hope we allow something like the following:
>> 
>> method doSomething(…) -> Done {
>>      … code to do stuff …
>> 
>>     // Don’t forget to add code here to take care of …
>> }
>> 
>> As writing note to one self about what must still be done is very useful.
> Freestanding comments, with either a blank line or } after, should be
> fine. Those aren't a problem for people or machines. There will always
> be a case for comments that introduce a group of related declarations
> each having their own specific comment, for example.
> 
> Possibly a comment without other attachment at the top of a block can
> be attached to the block as well. That is the other case that's hard
> to handle otherwise.
> -Michael