[JSR308] Revisiting array annotations

[Igor Peshansky]

Hi, everyone,

Apologies for the (rather long) HTML email -- I feel in this case it's 
somewhat justified.

Here are some (high-level) comments on section B.3:

The list of proposals is missing 2 items.  There are two separate 
dimensions of choices for array annotations: one is whether to place 
annotations inside the brackets, outside before the brackets (prefix), and 
outside after the brackets (postfix), and the other is whether the 
annotation refers to the array being accessed via the brackets or the 
elements being accessed via the brackets.  However, only the latter part 
of the second choice is explored for the prefix and postfix notations.  We 
ought to have choices 5 and 6 as follows (with old choices 5 and 6 
renumbered to 7 and 8 respectively):

5.      Outside brackets, prefix; refer to the array being accessed

The type of elements of @A Object @B [] @C [] is @A Object @C [].

The example variables would be declared as follows:
@Readonly Document[] array_of_rodocs;
Document @Readonly [] roarray_of_docs;
@Readonly Document[][] array_of_array_of_rodocs = new Document[2][12];
Document [] @Readonly [] array_of_roarray_of_docs = new Document[2] 
@Readonly [12];
Document @Readonly [][] roarray_of_array_of_docs = new Document @Readonly 
[2][12];

6.      Outside brackets, postfix; refer to the array being accessed

The type of elements of @A Object [] @B [] @C is @A Object [] @C.

The example variables would be declared as follows:
@Readonly Document[] array_of_rodocs;
Document [] @Readonly roarray_of_docs;
@Readonly Document[][] array_of_array_of_rodocs = new Document[2][12];
Document [] @Readonly [] roarray_of_array_of_docs = new Document[2] 
@Readonly [12];
Document [][] @Readonly array_of_roarray_of_docs = new Document[2][12] 
@Readonly;

I would argue that the postfix syntax will be confusing and unintuitive to 
Java programmers, for the following reason.  Java array syntax 
conceptually inverts array dimensions, in that the outer dimension comes 
first.  An array declared as @A T[@B] arr2d[@C] becomes @A T[@C][@B] arr2d 
in the Java array syntax.  Thus, postfix notation is really not very 
natural, as programmers will basically have to perform the double 
inversion in their head to parse the annotations.

Nor is it very natural for annotations to refer to the elements of the 
array corresponding to the brackets, since that separates the annotation 
from the type being annotated.  All in all, I believe principle P1 is more 
important for readability than principle P3.

IMO, the most appealing choice is the outside prefix notation with 
annotations referring to the arrays (choice 5 above).  The prefix part 
helps in that each annotation that precedes a pair of brackets can apply 
both to the outermost level of the array represented by those brackets, 
and to all of the successive dimensions (which are contained within the 
current one).  For example, imagine an @Align annotation that specifies 
that each subarray is alligned on a cache line boundary.  It would be good 
to visually indicate that containment (since the property of the outer 
arrays will imply some property of the inner ones).  Another good example 
for gauging what looks natural is the @Length annotation.  Using the 
outside prefix notation, @A T @Length(3) [] @Length(10) [] arr is more 
natural (easier for a human to parse) than @Length(3) T @Length(10) [] @A 
[] or  @A T [] @Length(3) [] @Length(10).

I've discussed the above with Doug Lea, who agreed with my arguments.

It might also be helpful to allow parentheses in type specifications, just 
to allow the programmer to visually disambiguate the hairy cases.  The 
caveat of this approach is that (@A T[@B])[@C] and @A T[@B][@C] will mean 
different things (which is a bit counter-intuitive).  Also, it was pointed 
out to me that @A(T[@B][@C]) might be hard to parse (it's ambiguous with 
@A(e) -- I have to take another look at the grammar to see if that is a 
serious problem).

One more thing that was brought to my attention recently is that Java does 
allow the following constructs:

   T x @A [];

and

   T m(...) @A [] { ... }

(the first is a variable of type T[], and the second is a method returning 
a T[]).
I feel that, ugly as those cases are, the syntax I proposed still looks 
reasonably readable and consistent...
        Igor
-- 
Igor Peshansky  (note the spelling change!)
IBM T.J. Watson Research Center
XJ: No More Pain for XML's Gain (http://www.research.ibm.com/xj/)
X10: Parallel Productivity and Performance (http://x10.sf.net/)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.csail.mit.edu/pipermail/jsr308/attachments/20071011/aefacd99/attachment.htm