Naming conventions for replacement APIs / classes

Question

Do you have a naming convention for APIs or Classes that are being phased in to replace an older version that performed the same function / filled the same role?

E.g. Windows does this by adding "Ex" to the end of the function:

ShellExecute // old
ShellExecuteEx // new

What do you prefer, and what are you reasonings?

• Appending 2, V2, New, NowInStereo?
• Doing a one-time rename of the old API from Something to SomethingOld and using Something for the new stuff? This option worries me when it comes to version control, but it also seems the least likely to be burdened with a V3 or ReallyNew problem in the future.
• Making up a completely different name that may describe the function less accurately, but at least is different.

Answer 1

You only need to create a new function if the arguments to the function are changed due to new requirements for the function.

The best naming convention for an API is the one the users of the API would expect. If the API is used only on Windows then adding an Ex (or Ex2 for the next rev) may be appropriate. I'm not aware of other conventions on other platforms. Also, your programming language may have a convention for extending API methods.

If you are using an object oriented language and this is an object method, you do not have to change the name because you can have methods with the same name and different signatures. However, it may still make sense to provide a new name to let users know that you want them to migrate to the new method.

Answer 2

Much of the time you can get away with changing the package name, rather than the class name itself.

Answer 3

Why change it at all? Interfaces being the contracts that they are, why would you break the interface after everything is using it.

Edit: Sorry to botch your comment Josh...

I think that if you've gone to the trouble to create the interface you need to do everything you can to maintain it. What kind of bad choice were you thinking about when you commented before?

Answer 4

If the new class performs the same function as the old one, I remove the old one and replace it with the new one with same name. I can still consult the old one in version control if needed.