Api maintenance

Adding functionality

The new functionality should be available for everyone. But you should give a warning, if people want to use a functionality that did not exist in the version that the user specified because that means that the user didn't choose the adequate API version (his code would crash, if it was really used with the version that he specified).

Note: Once added a functionality to the API in a release, it is hard to remove it again. You never get really rid of it, see below section "Removing functionality". So before adding stuff to the API, let it go for a day or two and think it over again after that time. Does it really make sense to add this function? Doesn't it expose too much CSnake internals to the user? Will refactoring be equally simple after adding the function? Could the function possibly break stuff?

Implementation summary:

• Older versions: Warning + Functionality (Add a method to API*Base that gives a warning and class (statically) the implementation in the subclass. Check if that static call is possible: The method of the subclass may rely on new class members that your base class doesn't have.)
• Newer versions: Functionality (override the above defined new method in a new subclass and implement the functionality there)

Changing functionality

If you want to change the behaviour of a function, keep both versions of the functionality and execute one or the other depending on the API version. No warnings are necessary.

Implementation summary:

• Older versions: Old Functionality (already implemented in old class versions, no need to touch it)
• Newer versions: New Functionality (override method in a new subclass)

Removing functionality

Normally you only want to remove functionality, if having the specified functionality breaks stuff, i.e. it's not an issue of the implementation, the problem exists because of the specified functionality itself, it cannot be fixed by changing its implementation. Unfortunately, for the sake of backwards compatibility, in old API versions you still need to keep the functionality and maintain it (so watch out when adding stuff, you won't get rid of it afterwards!). As you normally only remove functionality in severe cases, you should both give a warning in older API versions (the user should stop using the functionality, if he has the possibility to do so) and throw an exception, if people try to use the function in newer versions (so in those versions it's actually removed).

Implementation summary

• Older versions: Functionality + Warning (add the warning to the method implementation in all old versions)
• Newer versions: Exception (override method in a new subclass: throw exception)

Adapting the API to changes in the CSnake core

Adapt (all versions of) the API implementation so that the functionality (seen from the point of view of the CSnake file) in every version of the API stays the same as before the change.

General Hints

• Extend/modify/remove functionality creating new subclasses of the latest versions of the classes.
• Only modify older versions of classes, if that is necessary to keep its original functionality (see "Adapting the API to changes [...]") or to add a warning, if a function will be removed in future API versions (and is therefore probably harmful).
• Avoid calling public (and therefore in C++ terminology "virtual") functions, they will likely be overridden in the future, so you can't rely on their exact behavior.
• Within this module it is allowed to access private members of other (unrelated) and superclasses. This avoids the before mentioned (bad) call of "virtual" functions and avoids exposing internal details to the CSnake file

---

Back to the Developer Guide.