Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

3 Answers 3

up vote 8 down vote accepted

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.

share|improve this answer
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. –  MainMa 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

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)

share|improve this answer
1  
I was leaning towards "Experimental" after seeing APIs like developer.chrome.com/extensions/experimental.html –  Michael Levy Oct 15 '12 at 19:57

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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