Friday, February 15, 2008

The sly fox' clause

I am working on new status dialog for some time. And my work progress very slowly, so even if this code will be released for M6 it is impossible to make API stable. I do believe that 4 weeks is not enough to do that. This issue seems to have serious impact on my work - it is too late to release the code, because then it will go to API and should be maintained forever. I do not find myself good enough designer to take that risk...
So... should I postpone my work?
Actually I would have a lot of problems if Szymon Brandys and John Arthorne hadn't shared with me their knowledge (yes, they allowed me to write about this if I put their names in the note).
So, the trick is to put following comment into javadoc:

IMPORTANT: This class is <em>not</em> intended to be subclassed.

This little clause is warranty of binary compatibility in case of any changes. Well... actually it indicates there is no warranties at all, and if you try to derive from that API anything its your problem.

Of course I could use final clause. But then nobody would be able to use my classes and provide feedback...

The trick is called "soft API".

By the way, if you have a second or two please look at new status dialog.



Szymon Brandys said...

You can't take everything literally. Actually new API looks good, the only issue is that it can be tricky to subclass the new dialog :-)

Steve said...

There is only API and non-API. If you intend for people to subclass to use your new class, then this comment is misleading.

If you don't indend subclassing, then it's fine.

Christopher Daniel said...

Yes, I do intend subclassing.
But not right now.