Is there a good term that is similar but different than “deprecate” to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely change? (Yeah, I know, those methods shouldn’t be public, yada yada yada. I didn’t create my situation, I’m just trying to make the best of it.)
What do people suggest? Experimental, Incomplete, something else?
If I’m building javadoc documentation for this API that is still in flux, should I use the @deprecated tag or is there a better convention? To me @deprecated implies that this API is old and a newer preferred mechanism is available. In my situation, there is no alternative, but some of the methods in the API are not finished and so should not be used. At this point I cannot make them private, but I’d like to put clear warnings in the docs.
1
Appropriate term is most likely incubator, this is one used by Google and Apache:
-
google-web-toolkit-incubator
The Official incubator of widgets and libraries for Google Web Toolkit…
-
Apache Incubator
…the gateway for open-source projects intended to become fully fledged Apache Software Foundation projects…
If you take a closer look at the projects referred to above, you may notice that “experimental” APIs (eg in GWT) tend to have “dedicated” package names, like com.google.gwt.gen2. This is to avoid polluting future “finalized” API intended for permanent public consumption – because, you know,
“Public APIs, like diamonds, are forever. You have one chance to get it right so give it your best…” (Joshua Bloch, How to Design a Good API and Why it Matters)
1
I would use @deprecated for purely practical reasons.
Although @deprecated does not convey the exact meaning that you would like, it has a significant advantage: Java compiler has built-in support for it. Compiling with -deprecation flag lets you find all places where you override a deprecated method, helping your users find suspicious code very quickly. You can use @deprecated Javadoc tag to explain what is really going on to anyone who cares to read your documentation. This is where you could tell the user that the API is experimental, should be used at their own risk, and so on.
3
I’ve never seen anything like this in other APIs, since experimental or incomplete features have nothing to do in a public API.
Since you have no choices, just put a clearly visible warning that the part of the API is subject to change.
1