Review : 6546713: Link optional in Collection exception documentation to explanation

Stuart Marks stuart.marks at
Wed Apr 27 18:02:15 UTC 2011

On 4/20/11 5:07 AM, Lance Andersen - Oracle wrote:
> On Apr 20, 2011, at 7:41 AM, Doug Lea wrote:
>> On 04/19/11 21:07, David Holmes wrote:
>>> Hi Mike,
>>> Mike Duigou said the following on 04/20/11 08:00:
>>>> Hello All;
>>>> Another collections javadoc review request. This change links the "(optional)"
>>>> notes in on various Collection methods to text which explains why they are not
>>>> thrown by all collections.
>>> Generally looks good. I think you should revert this additional change in
>>> ! *
>>> "null" is used all over the place without being code font, including other
>>> @throws NullPointerException.
>> This, along with literals "true" and "false" are not code-fonted
>> very consistently. Someday someone should do a big consistency pass
>> across the whole code base.
> Perhaps we can document what we believe the standards should be WRT when to use {@code} .  I am sure I have clean up to do throughout the JDBC as well for consistency in this area

I think there is a preference for {@code foobar} over <code>foobar</code> but 
I'm not sure it's written down anywhere. The "What's new in Javadoc 5.0" page 
[1] says that "{@code abc} is equivalent to <code>{@literal abc}</code>." This 
is useful in case "abc" contains angle brackets, which needn't be escaped if 
@code is used. This is a good reason to use @code instead of <code>...</code>.

However, I think that <code> and @code are overused in general. If it's used 
for an actual code fragment, fine, but I really think it's unnecessary for 
single words such as true, false, and null used within running text. To use 
this specific example, is

     @throws NullPointerException if the specified array is {@code null}

really preferable to

     @throws NullPointerException if the specified array is null

? To my eye, the additional markup garbages up the javadoc source, makes it 
harder to edit, and it makes the formatted output harder to read. The most 
egregious example is {@code try}-with-resources. Check out java.lang.Throwable 
to see it in action.

Perhaps @code is warranted in cases that would otherwise be ambiguous, such as

     create a long array


     create a {@code long} array

But these cases are relatively rare.



More information about the core-libs-dev mailing list