Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
RE: [e4-dev] Package naming

I should have known bringing up naming conventions would start a holy war :)

[kosta] Nah. Just a minor skirmish.

Your main argument seems to be that this makes it easier to move across bundle boundaries, but I don't see how that matters. How does an internal package's name have any impact on your ability to move it across bundles?

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

What do you do when you have an internal package with no corresponding API package

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

Back to the top