On 20 December 2013 16:53, Stefan Bodewig <bode...@apache.org> wrote: > Hi > > in compress' trunk we now have to different stream classes that use > variants of LZW - the UNSHRINKING support in the zip package and the > ZCompresorInputStream. > > They looked so similar (and CPD was rightfully moaning about code > duplication) that I decided to extract the common code into > <http://svn.apache.org/repos/asf/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/compressors/z/AbstractLZWInputStream.java> > > As the two streams live in different packages I was forced to make the > base class public. It also introduces protected methods to > ZCompressorInputStream that give away more about the implementation than > I feel comfortable with - at least if we are forced to keep it stable. > > I'm looking for a way to properly state "this class is public for > technical reasons but it is not part of the public API of Compress and > may change between releases" - same for the protected methods, if > possible. > > Is it enough to say so in the javadocs? Should I move the base class to > yet another package with something like "internal" in its name in > addition to the javadocs?
I think that would be best. There may well be other refactorings that could make use of it. Also having the internal package will hopefully encourage future maintainers to consider what really needs to be public and what is not. And the package Javadoc can make it clear as well. I would try and make the package name stand out more - e.g. "_internal_" > How much effort is "enough" to allow future > releases breaking this part of the API? Difficult to say, but I suspect Javadoc alone is not sufficient to prevent accidental usage. > Stefan > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
