How to flag a class as under development in Java

Question

I'm working on a internship project, but I have to leave before I can finish up everything.

I have 1 class that is not stable enough for production use. I want to mark/flag this class so that other people will not accidentally use it in production. I have already put the notice in Javadoc, but that doesn't seem enough. Some compiler error or warning would be better.

The code is organized like this:

[Package] | company.foo.bar.myproject
          |-- Class1.java
          |-- Class2.java
          |-- Class3.java <--(not stable)

If there was a single factory class that calls those classes in public methods, I could have set the method to class3 as private. However the API is NOT exposed that way. Users will directly use those class, e.g. new Class1();, but I can't make a top-level class private. What's the best practice to deal with this situation?

Answer 1

Why not just check all the unstable classes into a different branch on your version control system?

Answer 2

If you have properly commented the class you could mark the bits of incomplete functionality as "deprecated" and or comment out the guts of the method and put a throw new UnsupportedOperationException();.

See Is there anything like .NET's NotImplementedException in Java? for details.

Answer 3

I do not know such compiler warning.

In your situation I would probably use the @Deprecated annotation. It will cross out method calls so it will be obvious to the others that something is up. When they look at whats up, they will see your comments about 'not production ready' and go AHA.

Answer 4

I don't think there is a standard way of marking code as WIP, Incomplete, or something like that.

You could create a new exception named ClassUnstableException and then raise it in the Class3 constructor with a message that explains how they shouldn't use it. This is bad though, because it only warns them at run time.

You could also try making the class incompilable in some way, and then add a note to the section of code that trips the compiler so that if someone goes to fix the code they will hopefully see an explanation of why they shouldn't use that class. This may not work if they use some semi-automated "fix this problem" tool that some IDEs have. This is also bad because it could break builds.

You could create an annotation named WIP (since the closest I can think of is Deprecated but it doesn't really mean the same thing) and use it to annotate the class. This would probably be a bit more work, and what would support the annotation?

Finally, you could just put it in the comments, but that will only work if people actually read them.

EDIT:

This may be relevant: How to intentionally cause a custom java compiler warning message?

Answer 5

You could introduce compile time annotation processing but this would enforce all members of the team to adjust their compile process.

However I find the whole process a little confusing. An unstable API should be clearly separated by creating a branch in your version control system. If it really has to be in the rest of the codebase, has been documented as unstable and nevertheless get's used the problem is not really technical but lies within the organisation and the communication. Yes, you could introduce technical verifications (like annotation processing) but that wouldn't solve the problem - just move it to another level.

So my recommendation is: If you cannot separate the code base by putting it in different branches then talk to people and explain to them why they mustn't use the API.

Answer 6

Why is it there in the first place?

You've checked unstable code into the mainline? Why?

Unstable code shouldn't be checked into trunk / main / master or whatever the main trunk name is. This is considered to be high risk development and should instead have been sequestered off in its own branch that you worked on rather than checked into main.

I would strongly encourage you (and your team lead) to read Advanced SCM Branching Strategies. In particular, pay attention to the development role and what it says about what is considered to be high risk development:

In general, consider using separate branches for each high-risk project. High risk projects are characterized by large size, large numbers of people, unfamiliar subject matter, highly technical subject matter, very tight time lines, uncertain delivery dates, incomplete or volatile requirements, and geographically distributed project teams. Similarly, consider designating a single branch for low risk development in each release. Several sources including [WING98] recommend using the mainline for this purpose. Consider the factors discussed above for the mainline before committing to this course of action. Low risk development may have different policy from the mainline even if you have multiple members of a product family coordinating through the mainline.

Letting people check unstable (or unused) code into mainline means that you will confuse future development efforts about trying to maintain this code. Every branch and clone of the rep from now until the end of time will contain this until someone says "its dead codE" and deletes it.

There are some that say "well, if its in a branch it gets forgotten" and while that may be true, having forgotten dead (and unstable) code in mainline is many times worse as it confuses all future development until it is removed - and then it is even more forgotten. A nicely named branch of "/fooProject/branches/WeisBigIdea" (or equivalent) is visible and easier to work with in the future - especially if it kind of works.

@Deprecated

The first thing is the @Deprecated annotation. This goes beyond the javadoc and spits out compiler warnings. javac provides a -deprecation flag that is described as:

Show a description of each use or override of a deprecated member or class. Without -deprecation, javac shows a summary of the source files that use or override deprecated members or classes. -deprecation is shorthand for -Xlint:deprecation.

As noted, this goes above and beyond the standard compiler warnings.

In many IDEs, deprecated methods and values are shown with a strikethrough:

foo.bar();

And would produce output like:

$ javac -Xlint:all Foo.java Bar.java
Bar.java:2: warning: [deprecation] Foo in unnamed package has been deprecated
interface Bar extends Foo { }
                      ^

Depending on your build structure, you may have warnings break the build. This would only break the build if one of your classes was used (not if it is just simply compiled in).

@CustomAnnotation

There are many approaches to this. For example, the Lightweight javac @Warning annotation which provides an annotation processor that fires off a warning at compile time when something with that annotation is used (a netbeans tutorial on custom annotation processors so you can get an idea of what is going on behind the scenes).

Oracle even describes an example of using custom annotations for an @Unfinished annotation in Making the Most of Java's Metadata, Part 2: Custom Annotations.

With the AnnotationProcessor, you can run arbitrary code at compile time. Its really up to you to decide what you want it to do. Warn, break the build when something is used. There are numerous tutorials out there on the web for how to write this sort of code. Whether you want to generate an error when its compiled (this will be annoying and lead to it getting deleted) or if its used (quite a bit more complex to write).

Note that all of this implies changing the builds to actually use the annotation processor.

Answer 7

Could you move all the incomplete classes into a subpackage named something obvious like "NOTCOMPLETE"? It's a bit of a hack but might be visible enough.

(If they are not all in the same package, you could recreate the package structure under there.)

Answer 8

I don't know that there is really a good way to do this in the code. Take a step back:

Create two copies of the whole project, one with the class, and one without. Mark the version without the class as a stable codebase, ready for production release, and the version with the class as development for a future release. Document what needs to happen before this class can be considered production-quality.

Ideally, you should do this using branches in your source control solution of choice. You might have to cheat a bit though, since it sounds like you haven't been using such a branching strategy. Carefully remove the new class, check in a version without it, and do some regression testing. When you're satisfied it's stable, you can tag that revision, create a development branch from the tag, and then add the class back in the development branch.

Answer 9

I'd opt for making the class abstract, and commenting appropriately - that way, the code is still there for reference, but good luck to anyone who tries to instantiate it :)

Answer 10

What about making a dependency that the compiler can't resolve? Just add:

import this.is.not.done.yet.do.not.use.it;

to the top. Users won't be able to compile with it.

If you want to test out the class, simply create a package/class with that name (or use a simpler one like "experimental.danger") and you can test the new code.