[JSR308] Annotations on statements and regularity

[Gary T. Leavens]

Hi all,

Here's another thought about why allowing annotations on statements may be
both good and somewhat tricky gramatically.

There are (at least) two ways to measure the simplicity of a
programming language.  The first is by looking at objective measures,
such as the size of the grammar for the language, or how much code is
needed to implement it.  The second is by thinking about how complex
the user's mental model of the language is; that is, how regular or
uniform is the language.  We should try to make both as simple as we
can to support the use cases we believe are important, but we
shouldn't ignore either of them.  The second is quite important for
how hard the language feels to use and learn.

This applies to statement annotations in the following way.
Consider the following method for a class BoundedStack (for Java 1.4,
sorry :-)

   public Object clone ()
   {
     BoundedStack retValue = new BoundedStack(maxSize);

     retValue.nextFree = nextFree;

     int k = 0;

     while (k < nextFree) {
       retValue.theItems[k] = theItems[k];
       k++;
     }

     return retValue;
   }

with the current Java 5 annotation syntax one can write annotations on
declarations, and hence one can write:

   public Object clone ()
   {
     @Peer
     BoundedStack retValue = new BoundedStack(maxSize);

     retValue.nextFree = nextFree;

     @LoopVariable
     int k = 0;

     while (k < nextFree) {
       retValue.theItems[k] = theItems[k];
       k++;
     }

     return retValue;
   }

Now, declarations are statements in Java, so naive programmers might
wonder why they can't just put annotations on all the statements.  Of
course, they can't because those aren't declarations.  So they have to
remember this distinction, which (slightly) complicates their mental
model of the language.  In essence, what I'm saying is that allowing
annotations on statements:

   public Object clone ()
   {
     @Peer
     BoundedStack retValue = new BoundedStack(maxSize);

     retValue.nextFree = nextFree;

     @LoopVariable
     int k = 0;

     @LoopCount(100)
     while (k < nextFree) {
       retValue.theItems[k] = theItems[k];
       k++;
     }

     return retValue;
   }

might in fact decrease the preceived complexity of the Java language
and the ease of learning and using it, since from a naive point of
view it makes the language a bit more regular.

This also shows, however, why it may be syntactically ambiguous to
allow annotations on statements, since declarations are also
statements, there is a risk of grammatical ambiguity if a declaration
statement can be annotated for two grammatical reasons.

         Gary T. Leavens
         Department of Computer Science, Iowa State University
         229 Atanasoff Hall, Ames, Iowa 50011-1041 USA
         http://www.cs.iastate.edu/~leavens  phone: +1-515-294-1580