Method signature best practices - overloading vs. long name

In my opinion, using verbose method name is a better solution.

• It's more understandable, your code will require less comments
• It's easier to maintain, you can change the implementation without impacting existing signatures. You still can add a new signature, without regression.

But be careful, in some situation it's preferable to add some parameters

Example 1

private List<Element> getElementsByType(MyTypeEnum type);

public List<Element> getElementsOfType1();
public List<Element> getElementsOfType2();
public List<Element> getElementsOfType3();

/* VS */

public List<Element> getElementsByType(MyTypeEnum type);

Both implementations are good, it depends on you, on the size of MyTypeEnum, on its capacity to increase in size. What do you want to expose ? Do you want the caller of getElements*** to be able to get all type of Element ?

Example 2

public void log(Level l, String s, Exception e);

/* VS */

public void logInfo(String s);
public void logWarning(String s);
public void logError(String s, Exception e);

In this case, the second part is better. Because it more readable, easy to understand on the first look. And because when you log in INFO and WARNING level, you don't need to specify an Exception. So Specializing the method is a good thing. However, it's important to keep the method public void log(Level l, String s, Exception e); public and not private because it could be useful to use this generic method in some cases.

Conclusion

It really depends on the situation but if you have the possibility to add specific methods, with verbose names, which specialize a target behavior, do it.

It all boils down to flavor.

As a general practice you can go with the "The least parameters the better". It's both convenient in terms of code clarity and it actually saves stack memory (not much, but every bit is important in the long run).

Having different names helps allot with auto complete as well.

For example i would go for

GetAllSubOrgUnitsList()
GetFirstSubOrgUnitsList()

The reason for this, after get, the first letter that I write will identify what i want.

As you mentioned, if you cannot have a intuitive name, you can add default parameters.

In your example,

GetDirectSubUnitsExcludingSome()

I would replace it with a minimal set of parameters

GetFilteredSuborgUnits(ISuborgFilter aFilter);

And then, from the architecture, ask developers to implement their custom filters. A filter can ask for hierarchial depth, certain ownership etc (you're the architect, you decide).

So, as a quick summary : KISS !

Even if GetAllSuborgUnits() will provide the same with GetFilteredSubOrgUnits(null) , giving a fast and clear alternative to a behavior is better then having a complicated name / set of parameters. After all, redundancies aren't always a bad thing :).

I don't agree that longer names is the better approach.

It does "depend", but let's clarify something:

• Two methods that do the same thing, but take different options should, IMHO, have the same name (be overloaded).
• Two methods that do different things (other than what is determined by parameters) should have different names. Put another way, there should be one name for a general function (albeit with variants), and separate names for different functions.

It's worth noting that overloading is the almost uniform practice used in the JRE.

I find little advantage in the longer names in practical usage. Granted:

 getSubOrgUnits()

Is more obvious than:

 getSubOrgUnits(true)

If I was including this in a formal API I would either give them separate names, or do the second one as a constant:

 getSubOrgUnits(INCLUDE_SUB_UNITS)

Though most IDEs allow you to see immediately see how the true parameter is interpreted by hovering over the method (which usually brings the Javadoc in a popup).

To me, the advantages of overloading is that it makes a formal association of the variants. It also is a nicer presentation in Javadocs.