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.

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?

share|improve this question
1  
What do you mean by "The API is not exposed through methods?" Is this class intended to be used via the Reflection API? –  Tom G Aug 10 '11 at 16:26
5  
A compiler error? Why not just throw an exception in constructor? –  Mchl Aug 10 '11 at 16:32
    
Sorry for the confusion. I have edited my post. –  Wei Shi Aug 10 '11 at 16:33
    
1  
You can't make the class private, but you can make its constructor private. –  Peter Taylor Aug 11 '11 at 12:15

9 Answers 9

up vote 13 down vote accepted

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

share|improve this answer
2  
Seems to me that this would 'hide' the code. What if the code almost does what others need it to do with some minor tweaks. If you put it in a branch they might never see it and would just re-implement the whole thing. –  c_maker Aug 10 '11 at 17:21
3  
@c_maker: Letting others know the branch exists and what's in it should be a part of what gets passed on when he leaves. –  Blrfl Aug 10 '11 at 17:52
2  
@Birlf If he is worried about others not seeing the explanation in the JavaDoc of code that they are using, I doubt that they will go looking for the other documentation that he produces. –  KeithB Aug 10 '11 at 21:21

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.

share|improve this answer
2  
method calls only get crossed out if the IDE supports it. –  FrustratedWithFormsDesigner Aug 10 '11 at 16:52
1  
True, but most people will probably use one of those IDEs that supports it. –  c_maker Aug 10 '11 at 16:55

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.)

share|improve this answer

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?

share|improve this answer
    
throw exception makes the eclipse complain about unreachable code. Any workaround? –  Wei Shi Aug 10 '11 at 17:01
    
@Usavich: Not sure since I haven't seen the code, but maybe that could also help prevent future developers from using the code? –  FrustratedWithFormsDesigner Aug 10 '11 at 17:04
    
@Usavich: Have a look at the link I added in the EDIT in my post, it's a similar question where the OP wanted to add a custom compiler warning. Might help you add a custom "UnstableCode" annotation. –  FrustratedWithFormsDesigner Aug 10 '11 at 20:19

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.

share|improve this answer
2  
This is the defacto way of dealing wit hit as I understand things –  Martijn Verburg Aug 10 '11 at 17:25

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.

share|improve this answer

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.

share|improve this answer

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 :)

share|improve this answer

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.

share|improve this answer
    
The compile will fail even if I don't use it ... bad idea ... –  Silviu Burcea May 13 at 11:33

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.