| RE: [e4-dev] Package naming |
|
I should have known bringing up
naming conventions would start a holy war :) [kosta]
Nah. Just a minor skirmish. [kosta]
I would say that the main part of my argument has more to do with
organizational improvements. Regarding bundle moving part of the argument, the
reason it matters is that even though we are talking about internal code and we
don’t make any guarantees that it will not change, it is still rather
nice to limit the scope of the changes that are necessary when re-visiting “how
things are organized into bundles” decisions. It means less work for
committers (not having to re-package) and less changes to early adopters who
might be using your internal code. [kosta]
See the last paragraph of my previous e-mail. If there is even a remote chance
that you might want to add API for this functional area in a later release, I
would recommend “reserving” the namespace for it by picking the
internal package namespace to account for it. If there is really never going to
be API for this, then there is nothing wrong or inconsistent in having
additional packages after “internal”. The approach that I described
says that the split between API and internal code should happen as late as
possible in the package structure, but it does not say that “internal”
has to always be the last segment. , or an internal package that
provides implementation pieces for several API packages? [kosta]
Perhaps it’s time to repackage. This case most often comes up when
internal code started out without API and the package structure didn’t
anticipate future API addition. It seems to me that a
convention of putting internal "as late as possible" will inevitabily
lead to inconsistencies as the set of API and internal packages evolves (both
because it's a judgement call, and because the mapping between API and internal
packages changes over time). [kosta]
It doesn’t matter which convention you pick. There are always judgement
calls involved, mistakes made, things not anticipated, etc. A convention just
serves as a guide of what should be done. Although the package namespace
is "flat" in the Java language, I think the value of putting
"internal" as high as possible is to avoid polluting the API
namespace with internals. I.e., when "internal" is a suffix, it
appears that the internals are a child or sub-package of the API, and hence
part of that API namespace. To me it is valuable that you can say for example
that the entire java.* namespace is API, javax.* namespace is extensions, and
com.sun.* namespace is internals. Whether a package is API or internal is
"more important" for consumers than what component or team developed
it. [kosta]
Two comments on this... This is partly a tooling issue as tooling could be
doing more to differentiate internal code from public code when browsing for
classes or during code completion. The other part is that I would urge everyone
to be very careful in assuming that the API consumers are only interested in your
public API. While that becomes progressively more true as a component matures,
it is very typical for your early adopters to be relying on internal code
during your developing years. Even if you have fairly decent API already, there
will always be something you haven’t anticipated or haven’t been
able to dedicate resources to exposing as API (take a look at JDT or PDE for
many examples of this). Even in the case of mature components with very good
API, your consumers still need to be able to locate your implementation classes
when debugging problems. I would argue that consumers are also benefiting from the
organizational pattern that I described. Then there is persistent problem of
converting your consumers into contributors. The easier you make it for me to
find the code that I need to modify in order to fix a bug that I just discovered,
the more likely I am to take the time to contribute a patch. |