12

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.

  • A "Unstable" tag would also be helpfull. The meaning would be something differente. "This is supposed to work OK but we might make some changes in the future". – Borjab Aug 12 '15 at 16:02
8

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)

10

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.

  • 1
    +1. Excellent point. Having a built-in support is essential for such parts of the API, and encourages the users to see the documentation to understand why are those parts marked as depreciated. – Arseni Mourzenko Oct 15 '12 at 20:01
  • 2
    I was leaning towards something like "* @deprecated This is an experimental API and likely to change" at a minimum to get the IDE and the docs to highlight the method and then to have a brief explanation. – Michael Levy Oct 15 '12 at 20:02
  • Just rememeber that deprecated will create a lot of warnings. This might not be as bad as it seems. Being warned of experimental features could be OK. – Borjab Aug 12 '15 at 16:04
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.

protected by gnat Nov 12 '18 at 15:54

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

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