0

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.

halfer
  • 19,824
  • 17
  • 99
  • 186
Jeffrey Blattman
  • 22,176
  • 9
  • 79
  • 134
  • Primarily opinion but no. Use unit tests and version control. Don't leave redundant / vestigial code to rot or pay down later as technical debt. – Elliott Frisch Apr 04 '19 at 16:24
  • I recommend reading Clean Code by Robert C Martin (Uncle Bob). – Luke Garrigan Apr 04 '19 at 16:27
  • @ElliottFrisch there are cases where methods simply can't be removed. For example, a public SDK where backwards compatibility can't be broken. I'll make it more clear that's what I'm asking about. – Jeffrey Blattman Apr 04 '19 at 16:36
  • 1
    @JeffreyBlattman Now it sounds like you're asking about [versioning an api](https://stackoverflow.com/q/389169/2970947). – Elliott Frisch Apr 04 '19 at 16:39
  • Note that the "new version of the method" is not effectively a new version: The old version remains in use. If the intent is to create a historical record of the method versions, that is a job better left to version control. If there is an intent to provide two different implementations using the same API, a descriptive name is better. Distinguishing implementations by version number does nothing to describe what is different about the implementations. (But, the point re: overlong names is taken. Setting good descriptive names is a careful art, and compromise is often necessary.) – Thomas Bitonti Apr 04 '19 at 17:13
  • @ThomasBitonti no the intent is not at all to keep a historical version, it's all about not modifying the semantics of an existing method that is already being used. Thanks for your input. – Jeffrey Blattman Apr 04 '19 at 18:25

1 Answers1

1

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.

Adam Burke
  • 724
  • 1
  • 7
  • 21