On 25 November 2011 16:55, Bill Speirs <bill.spe...@gmail.com> wrote:
> On Wed, Nov 23, 2011 at 4:47 PM, sebb <seb...@gmail.com> wrote:
>>> - @SuppressWarnings("unchecked")
>>> + @SuppressWarnings("unchecked") // cast exception will immediately be
>>> thrown and warn the developer
>>
>> Sorry to keep going on about this, but that does not fully explain why
>> it is safe to ignore the unchecked cast.
>> And it does nothing to tell the user of the API that they may get a
>> CCE or what they need to do to avoid it.
>>
>> In this case, what ensures that the cast will succeed?
>> Does that condition always hold?
>> If not, the Javadoc needs to say under what conditions the CCE will occur.
>>
>
> As we discussed before, this exception will be thrown if the column
> type doesn't match the generic type. Because of type erasure I don't
> know of any way to validate the types.
What determines the column type?
If the user codes correctly to the API, is it possible for the CCE to be thrown?
> Sebb, are you advocating putting an @throws ClassCastException in the
> Javadocs stating that if the column type doesn't match the generic
> type, then this exception will be thrown?
Yes.
The idea is that there should not be any surprise exceptions for
conditions that can occur in normal use.
That's where the Javadoc comes in.
Also for the maintainer of the code to understand why the warning was
suppressed, which is where the local comment is used.
Part of the idea of generics is to do away with unnecessary casts and
instanceof checks; adding inappropriate @SuppressWarnings tags negates
the benefit (and can even make things worse).
So each warning needs to be considered carefully, and any decision to
add suppression needs to be documented with the reasoning.
> What would others like to see for documentation here?
>
> Thanks!
>
> Bill-
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
