How to tag a method / API as experimental?

Question

I'm developing a framework which has a class called StableClass. This class is "stable": Users can rely their code on this class. Future versions of the framework will have this class, and it will be backwards compatible.

What I want is to add a method into this class, but I want to tell the users that this particular new methods is experimental, and might change in the future.

example:

class StableClass
{
public:
    void stableMethod1();
    void stableMethod2();
    void stableMethod3();
    void unstableMethod(); // How to tag this method as experimental ?
};

Users should know the unstableMethod() is experimental. That the API might change in the future (or not).

Possible options:

• add the experimental word as a suffix or prefix on the name. eg: unstableMethod_experimental()
• log to console every time the method is invoked
• tag it as deprecated, but in the warning says that it is experimental

Any other option ?

I would like to have the experimental attribute, and that the compiler raises a warning at compile time (like the deprecated attribute), but as far as I know, such attribute doesn't exist.

[UPDATE]:

I want to release a stable version of the framework, with a few APIs tagged as experimental. Sometimes it takes time to find the correct name, or the correct parameters or the correct functionality for a particular method, or implement it for all the supported platforms.

I want to tell my users that "this is the new stable version of the framework. We also added this new feature but it is experimental since it has the following limitations: ...".

So, I have this requirement where stable versions could have experimental features. Although it might sound like a contradiction, it is a requirement for me.

Answer 1

#ifdef EXPERIMENTAL
    void unstableMethod(); // How to tag this method as experimental ?
#endif

Hiding unreliable methods under appropriate defines will force users to alter their projects/targets preprocessor setting so they'll be aware of what they are dealing with.