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

[Girish Maskeri Rama <Girish_Rama@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. 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.

 

    Would you be kind enough to respond to the following

    questions:

 

    1.  Would you agree that this is a usability problem?

 

    2.  In your opinion, how important is this problem (and

        other such problems)?

 

    3.  Do you think a tool that automatically detects such

        API usability problems (maybe just before a release)

        would be useful?

 

 

    Shown below are the API declarations for the methods in

    question:

 

    (1)  static void replace(char[] array, char[] toBeReplaced,

                                                                               char replacementChar)

 

    (2)  static char[] replace(char[] array, char[] toBeReplaced,

                                                                               char[] replacementChars)

 

    (3)  static void replace(char[] array, char[] toBeReplaced,

                                                char replacementChar, int start, int end) 

 

    (4)  static void  replace(char[] array, char toBeReplaced,

                                                                                   char replacementChar)

 

    (5)  static char[] replaceOnCopy(char[] array, char toBeReplaced,

                                                                                   char replacementChar)

 

 

    Again, if you could PLEASE respond to the three questions listed

    above, we would be much appreciative.

 

    Thanks.

 

    Girish Maskeri, Infosys       (Girish_Rama@xxxxxxxxxxx)

 

    Avi Kak,  Purdue University   (kak@xxxxxxxxxx)

 

**************** CAUTION - Disclaimer *****************
This e-mail contains PRIVILEGED AND CONFIDENTIAL INFORMATION intended solely 
for the use of the addressee(s). If you are not the intended recipient, please 
notify the sender by e-mail and delete the original message. Further, you are not 
to copy, disclose, or distribute this e-mail or its contents to any other person and 
any such actions are unlawful. This e-mail may contain viruses. Infosys has taken 
every reasonable precaution to minimize this risk, but is not liable for any damage 
you may sustain as a result of any virus in this e-mail. You should carry out your 
own virus checks before opening the e-mail or attachment. Infosys reserves the 
right to monitor and review the content of all messages sent to or from this e-mail 
address. Messages sent to or from this e-mail address may be stored on the 
Infosys e-mail system.
***INFOSYS******** End of Disclaimer ********INFOSYS***