Naming methods that do the same thing but return different types

Let’s assume that I’m extending a graphical file chooser class (JFileChooser).

This class has methods which display the file chooser dialog and return a status signature in the form of an int: APPROVE_OPTION if the user selects a file and hits Open /Save, CANCEL_OPTION if the user hits Cancel, and ERROR_OPTION if something goes wrong. These methods are called showDialog().

I find this cumbersome, so I decide to make another method that returns a File object: in the case of APPROVE_OPTION, it returns the file selected by the user; otherwise, it returns null. This is where I run into a problem: would it be okay for me to keep the showDialog() name, even though methods with that name — and a different return type — already exist? To top it off, my method takes an additional parameter: a File which denotes in which directory the file chooser should start.

My question to you: Is it okay to call a method the same name as a superclass method if they return different types? Or would that be confusing to API users? (If so, what other name could I use?)

Alternatively, should I keep the name and change the return type so it matches that of the other methods?

public int showDialog(Component parent, String approveButtonText) // Superclass method
public File showDialog(Component parent, File location) // My method

Why do you need to extend this class? And why do you need to name your own method the same as showDialog?

In reality your method does something entirely different than what showDialog does. A better name for your method would be showDialogAtLocationAndReturnSelectedFile as your method does more or less these things. Naming it showDialog will only confuse your code users.

Also, without knowing anything else, I’d say you’re trying to shove too much in a single method. How do you react on a cancel press? How about an error? Do you return null? If so, you’re forcing the user of the code to check the return value yet again. This has the potential of being just another “Leaky Abstraction”, and Java APIs already have enough of these.

An important part of API design is making sure that the name of a function/class/method matches what it really does. And that is why in JFileChooser the method’s name is showDialog. It just shows the dialog. It doesn’t open the file for reading, it doesn’t perform a check whether the filename is valid, and honestly, why would it? The user of the code just asked the class to show the dialog.

The creator of Ruby calls this the ‘Principle of Least Surprise’*, and while I don’t really know Ruby, this is a great line to learn from. Your code should be in the service of its user, and a part of this service is embedding the contract of the method/class in its name.

You might think you’re not designing an API, but I doubt you work alone: there’s probably someone else in the team, and they will appreciate this. Also, I heartily recommend this lecture on API Design: How To Design A Good API and Why it Matters. It was presented to Googlers by a Java designer, so it kinda matters.

Maybe this is more than you asked for, but I feel you seem to be somewhat missing the point of naming methods.

UPDATE: * I seem to be mistaken, the creator of Ruby has actually stated that he designed Ruby with the “Principle of Least Astonishment”, not “Principle of Least Surprise”. In any case, what I said still holds.

The major problem I can see with this is that if I use your method like this:

chooser.showDialog(parent,location).getPath()

it will work perfectly most of the time, but if the user changes their mind about loading a file and hits cancel, the program will crash. You could say that I shouldn’t write code like that, and you’d be right, but people do write code like that sometimes. The method as written isn’t convenient, since you still have to check for null, and it’s a bit of a trap for anyone not paying sufficient attention.

As far as I can tell, you’re trying to abstract out 2 method calls into one, but it’s quite possible that the new method would be just as cumbersome after factoring in the need for a null check. It’s possible that the whole workflow you’re dealing with could be reasonably abstracted, in which case whatever you’d call the whole workflow would probably make a good name for a method.

To answer your actual question, I don’t think that having methods of the same name that return different types is automatically bad, but names and return types should never be confusing.

Filed under: softwareengineering - @ 19:10

Thẻ: inheritance, java, methods, naming, return-type

Thiết kế website giá rẻ

Danh mục

Naming methods that do the same thing but return different types