You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Stefan Bodewig <bo...@apache.org> on 2013/12/20 17:53:31 UTC
[compress] Marking a public Class non-Public
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? How much effort is "enough" to allow future
releases breaking this part of the API?
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [compress] Marking a public Class non-Public
Posted by Gary Gregory <ga...@gmail.com>.
I like the .internal. package convention (at least how Eclipse does it) but
this will not stop someone from using methods in the class through
inheritance but it makes it obvious if a class with a .internal. shows up
in an import statement. Using "Private" or "Internal" or "Impl" in the
class name is another style.
Gary
On Fri, Dec 20, 2013 at 11:53 AM, Stefan Bodewig <bo...@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? How much effort is "enough" to allow future
> releases breaking this part of the API?
>
> Stefan
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/>
JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
Spring Batch in Action <http://www.manning.com/templier/>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Re: [compress] Marking a public Class non-Public
Posted by sebb <se...@gmail.com>.
On 20 December 2013 16:53, Stefan Bodewig <bo...@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-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org