Re: [jdt-core-dev] API usability issue of overloaded method 'replace' in

[Srikanth S Adayapalam <srikanth_sankaran@xxxxxxxxxx>]

jdt-core-dev-bounces@xxxxxxxxxxx wrote on 18/04/2011 15:06:50:

> From: Girish Maskeri Rama <Girish_Rama@xxxxxxxxxxx>
> To: "jdt-core-dev@xxxxxxxxxxx" <jdt-core-dev@xxxxxxxxxxx>
> Date: 18/04/2011 15:06
> Subject: [jdt-core-dev] API usability issue of overloaded method
> 'replace' in org.eclipse.jdt.core.compiler.CharOperation
> Sent by: jdt-core-dev-bounces@xxxxxxxxxxx
>
> Hello,
>
>     Our interest in API usability issues has led us to the
>     following observation that we believe is an example of a
>     usability problem with the JDT-Core API:
>
>     Of the four overloaded methods named ‘replace’ in the
>     API of the class
>
>          ‘org.eclipse.jdt.core.compiler.CharOperation’
>
>     three of the methods modify the character array in
>     place.  On the other hand, one of the methods (number 2
>     below) returns a new array. One could expect this to be
>     confusing to the users.

The javadoc attached to the methods clearly state the behavior a client
can expect. There is value in having an API method that performs in place
substitutions and another that leaves its argument in tact, so a client
can choose based on need.

>Moreover, there exists another
>     similar method, named ‘replaceOnCopy’, that returns a
>     new array and does not modify an existing array. This
>     appears to be inconsistent, to say the least.

This method takes different parameters and does something slightly
different.

>     1.  Would you agree that this is a usability problem?
>
>     2.  In your opinion, how important is this problem (and
>         other such problems)?

It is not uncommon for utility classes to have numerous methods that
only differ a little bit from each other.

Srikanth