Consider this situation: there is a method getFoo(). It now becomes appearent that the method as-is is not useful or even encourages faulty code to be written upon it. A breaking change (e.g. returning a collection instead of a single item) must be made but the name of the method is still fine.

Do such changes have a special term? If yes: which?

Also: what is the best way do deal with such changes; how to warn users about them (since there is no function you could deprecate)?

As far as I understand "deprecation", it is meant to signify that a function/method will be completely removed in some future version of the software/API.

  • 1
    There is likely no well-defined name for such a situation because it is a bad idea to do so. Names are not a finite resource, so creating a different name for a method that does a different thing should not be a big deal. – BobDalgleish Nov 8 '19 at 19:24
  • @BobDalgleish that may be the case in some programming languages and frameworks, but not all. For example Ruby on Rails makes these kinds of changes fairly frequently; in Rails 5 for example this happened: eileencodes.com/posts/… This seems to be a deliberate design decision, as the creator has said "Whenever I stumble across something I don't like, I change it." interviews.slashdot.org/story/16/08/30/1759216/… – Maltiriel Nov 8 '19 at 20:33
  • 2
    How is this opinion-based? There's either a term for it or there isn't... smh – istrasci Nov 9 '19 at 1:18
  • If you think about the new version as being a different method that happens to do the same thing, but has a different interface, then that's essentially deprecation of the old version. – Filip Milovanović Nov 9 '19 at 9:37
  • 2
    This is called a breaking change to the API, or a change which is not backward compatible. How acceptable such a change it is depends on the degree of control you have over the code which uses this specific method, it is not necessarily a "bad idea" in general. – Doc Brown Nov 9 '19 at 19:07

Deprecated means in its general sense to disapprove something or to give it little value. In the software context, it means to discourage the use of a feature.

In the Java Community, for example, deprecated has indeed frequently the meaning of a future removal. But this is not the only reason:

the API has been superseded by another API,
the API is obsolete,
the API is experimental and is subject to incompatible changes,

According to this interpretation, incompatible changes could also be covered by the term deprecation. So there is not really a need for a new term.

But regardless of how you call this change in the API, this is not a good practice, unless you're still in preprelease (release 0 in the semver API versionning scheme):

  • Keeping the same function name with a different interface forces the users of the API to do the change timely with your new API publication. They have no way to adapt their code in advance, but as soon as you release the new API they have to quickly update every call. This is very inflexible ! Your users may have to block a release cycle for your adaptations.
  • Keeping the old function with the old signature, but deprecated, and introduce the new function with the new signature under a new name, allows you to let both versions coexist temporarily. The users can then migrate their code to the new API at their own pace over several of their releases. This is much more user friendly (and professional).
  • Of course, if the language supports overloading and accepts the same name with both signatures and without ambiguity, you may let both deprecated and new function coexist under the same name.
  • Keeping the same function name with a different interface **forces the users of the API to do the change timely** with your new API publication. This is also true for deprecated methods that will be removed. The time frame the users have to change their code to remove the usage of the deprecated methods is exactly the same (my assumption is that the "repurposed" methods will remain unchanged during the "buffer" interim before ultimately changing). So I don't see any validity to this point. – istrasci Nov 8 '19 at 21:10
  • 2
    @istrasci So essentially what you're doing is deprecating a method, then, at the time you remove it, introducing a new method with the exact same name but a different functionality and return type? Still sounds like really bad idea. – 1201ProgramAlarm Nov 8 '19 at 21:38
  • @istrasci It is true that you can inform well in advance in both cases. But with the same name, it is a hard switch: before your release your user cannot anticipate-not even a poc; once you’ve released the user must do the necessary to switch. If it’s a big system with hundred of modules using your API, it’s a heavy constraint. With the new name, you can offer a tolerance period, deciding when you introduce, and when you remove, temporarily offering both and let users in control – Christophe Nov 8 '19 at 21:49
  • Just think of this as deprecating an older version of the method (in terms of interface). No need for a new term. – Filip Milovanović Nov 9 '19 at 9:40

Not the answer you're looking for? Browse other questions tagged or ask your own question.