Sponsor for 6666666: A better implementation of Character.isSupplementaryCodePoint

[Ulf Zibis]

Am 24.03.2010 20:34, schrieb Martin Buchholz:
> On Wed, Mar 24, 2010 at 10:20, Ulf Zibis<Ulf.Zibis at gmx.de>  wrote:
>    
>> Am 23.03.2010 23:59, schrieb Martin Buchholz:
>>      
>    
>> I too would like to see 8 spaces indentation on line breaks like:
>>     if (aaaaaaaaaaaaaaa>  bbbbbbbbbbbbb&&
>>             ccccccccccccccc>  ddddddddddddddddd)
>>         doSomething();
>>      
> This appears to be a new style (perhaps coming from the java IDEs?)
>    

This rule is much older: 
http://java.sun.com/docs/codeconv/html/CodeConventions.doc3.html#248
But yes, I first saw this from NetBeans IDE formatting facility.

> but it would be too pervasive a change for the JDK sources.
>    

but wouldn't be a big deal for old stagers when coding new lines. ;-)

>    
>> + opening braces at line end instead beginning a new line
>>      
> Perhaps too difficult/controversial?
>    

Yes, you will know that better from your team.
See: http://java.sun.com/docs/codeconv/html/CodeConventions.doc10.html#182

>    
>> + blank line between package ... and import ...
>>      
> This could be done, and automated.
>
>    
>> + no blank line between javadoc and class/method declaration
>>      
> Yes.
>
>    
>> + 2 spaces after period
>>      
> I agree with this style, but there is not enough consensus.
>    

See comment for braces at line end.
See: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#examples
See: http://java.sun.com/j2se/javadoc/writingdoccomments/package-template

>    
>> + proper indentation in @param @return @throws blocks
>>      
> Perhaps too difficult to automate?
>    

I can understand. For the Character class I did it manually.
See: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#format
I guess we can ignore the 2nd column tabulator, especially if names 
become looooong

>    
>> + not too much use of braces e.g. for 1-line blocks (one can see more code
>> lines on same screen space)
>>      
> I agree with this personally, but there is violent disagreement
> in the java programmer community.  E.g. google's style guide
> requires braces everywhere.
>    

IMO, this should not be followed too bureaucratic. Think about 
labtop/netbook users or plenty open windows from IDE.
Additionally scrolling becomes a kinda nightmare.
And as you can see in the existing code base, things are never as bad as 
they seem, or the devil is not as black as he is painted. ;-)

>    
>> +
>>      * @see    #forDigit(int, int)
>>      * @see    Integer#toString(int, int)
>> instead:
>>      * @see     java.lang.Character#forDigit(int, int)
>>      * @see     java.lang.Integer#toString(int, int)
>>      
> I did a global s/java\.lang\.// in Character.java.
>    

As justified before, I would drop the current classes name.
See: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#tag

>    
>> +
>>          * range: U+DC00 through U+DFFF
>> instead
>>          * range: 0xDC00 through 0xDFFF
>>      
> I disagree.  The U+ notation should be reserved for
> Unicode characters (code points) and not UTF-16
> code units (which surrogates are).
>    

I fully agree, but in the context, where I wanted to change this, the 
matter actually was about code points, not code units, and ...
in case of Java char/UTF-16 code units, IMO we should use \u notation.
0x notation should only be used for none Unicode charsets binary values.

>    
>> +
>>     {@link #isLowSurrogate(char)}
>>     {@link Character.UnicodeBlock}
>> instead
>>     {@linkplain #isLowSurrogate(char) isLowSurrogate}
>> <code>{@link Character.UnicodeBlock UnicodeBlock}</code>
>>      
> I've removed the<code>  above.
>    

BTW, I can't find any docu about {@linkplain ...}.
What is the advantage against simple {@link ...}?

Additionally I like to mention for class Character:
- numerous javadoc blocks are only indented by 3 instead 4 spaces.
- some code lines are indented by 5 instead 4 spaces.
- I still dislike the space after a cast, refer to internal review ID of 
1740052.
- several UnicodeBlock declarations differ little in 
indentation/whitespace usage from the average. I would prefer:
         public static final UnicodeBlock SUPPLEMENTARY_PRIVATE_USE_AREA_A =
             new UnicodeBlock("SUPPLEMENTARY_PRIVATE_USE_AREA_A",
                              new String[] { "Supplementary Private Use 
Area-A",
                                             
"SupplementaryPrivateUseArea-A" });



-Ulf