CODEWITHSUNDEEP
javacode-structure
Jeffrey Blattman
Jeffrey Blattman

Reputation: 22637

Numeric suffix to methods: is it a valid style? (e.g. myMethod2())

This is a style question, and in the context of a public SDK where methods can't be removed because of backwards compatibility requirements.

I've seen in some places where when a new version of a method is added, it will have the same name but some numeric prefix, e.g.,

void doTheThing2(...) {...};

At first glance this is pretty ugly and obviously doesn't do anything to communicate the actual difference in the method. On the other hand, I've found that it's often even uglier and sometimes just impossible to capture the semantic change in "version 2" of the method in the name. E.g.,

boolean doTheThingButReturnResultCode(...) {...};

And god forbid if you have a version 3 of the method, then what?

Obviously I'm coding in Java but this question isn't specific to Java. And I realize there's no objective answer here, but hoping to get some opinions with rational.

Upvotes: 0

Views: 226

Answers (1)

Adam Burke
Adam Burke

Reputation: 864

I would say it's discouraged, but not invalid. I think you very much have the right idea in maintaining back compatibility of methods over significant periods of time in a public API, with clearly advertised deprecation periods.

One problem with suffixes is that the new method will eventually, say after 1-2 major API versions, become the main method to use. Yet this undermines the flow of the working programmer - you get a legacy suffix still attached to a method. Even before this, the meaning between method() and method2() is usually not a clear convention.

Since English is a language rich in synonyms, I have seen these be preferred to version suffixes at the method level. This is usually less of a sacrifice of clarity and simplicity. Eg addItem() (deprecated) might become storeItem(). This works particularly well when the new naming convention can be followed in multiple places in the API. Then addWidget() and addWudget() become storeWidget() and storeWudget().

You can see this synonym approach is in the Java and Python APIs themselves - they rarely use numeric suffixes. Perhaps the String.subSequence() method could be considered a version 2 of String.substring().

Another problem with numeric suffixes is it's not clear what the number is a version of. Is it a version of the method? Of the API? A year? A Java version? The API major version probably makes most sense, but it's hard to give this context consistently without adding a longer suffix like addItemJava2() or addItemV2(). It also becomes unintuitive using the orphaned numeric suffix after the major API version changes. Should I be using addItemv3() now it is API version 5?

I have seen numeric suffixes used a bit more effectively in interface and class names. Perhaps this is because they are more usually nouns, rather than verbs, which are more common in method names. It makes more sense to have a CarModel2 than a drive2(). Or perhaps because they are interfaces the consistent context is easier to impose across a wider surface of the API and so have the user of the API discover.

As this concerns style, some of this may be subjective, but those are some design pressures to consider.

Upvotes: 1

Related Questions