Apply package naming rules consistently

Description

In Search we decided to make the spi/impl/public split at the leave level(s) of the package structures. Meaning for example impl packages should always be leave package names. That is not the case for example for org.hibernate.search.backend.impl and its sub packages.

Environment

None

Activity

Show:
Sanne Grinovero
June 7, 2013, 3:46 PM

not at all what I meant.

I know But if your point is easier coding + code structure, then I'm pretty sure it is easier to keep related code together.

Gunnar Morling
June 7, 2013, 3:57 PM

First off, I get that this issue really seems to be subject to personal preference, so I think there is no much point in convincing someone who prefers it the other way around. I'm still gonna try it

How is that distracting?

To me, a library has two major parts, public-facing parts (API/SPI) and non-public parts (internal). I find it just much easier to handle (as a developer of that library but also as a consumer) if this split is done at one place, i.e. at the top of the hierarchy. Once I'm in either sub-tree, I don't have to deal with the other half any-more.

When the split is done on the leaf-level, I as a user stumble upon internal packages again and again, e.g. when navigating through the package tree of the library, but also when working with auto-completion. In the top-split model, once I've tabbed to org.hibernate.search.foobar, my IDE will never suggest any impl type again. In the leaf-split model, it will suggest impl types for each new sub-package I'm tabbing into.

Sorry I don't mean it with sarcasm I'm genuinely not getting it, especially not why this is so important vs. keeping an existing API as is.

But my suggestion is exactly to leave the "API" as is (comprising API and SPI packages) and only move the impl packages to a separate sub-tree, moving it out of sight for a consumer of the library. I don't see why leaving the impl packages at the leaf level makes the library better consumable for users, IMO the opposite is the case.

Btw. I really appreciate your non-sarcasm, this greatly helps with keeping the discussion productive. Regarding importance, it's surely not super-important, but personally I just feel that the top-split model makes a library better consumable.

Sanne Grinovero
June 7, 2013, 4:14 PM

You're right it is very personal. We all tempt to like the things as we are used to as that feels more natural, but of course many other people use it and have different opinions so whatever we choose someone won't be happy; we can argue to make the "someone" a small group, but even so that choice might not be the same as you would pick in a "truly better" strategy. I firmly believe the only strategy which guarantees the least annoyance is the no-change: too bad we got it "wrong" (even assuming it is) initially.

For the sake of fun argumentation only: The think with splitting .impl only removes the "self documenting" aspect of it as you won't have an impl vs. spi but just an impl standalone in a long list of other API packages.. it's not standing out as special, we can't use a red font.

Hardy Ferentschik
June 7, 2013, 5:32 PM

I don't see why leaving the impl packages at the leaf level makes the library better consumable for users, IMO the opposite is the case.

Same here. I cannot really put into any other words.

I firmly believe the only strategy which guarantees the least annoyance is the no-change: too bad we got it "wrong" (even assuming it is) initially.

Here I highly disagree with you . If we were to agree that the opt level split would be the better approach, then it would make to change. Sometimes disruptive changes make sense and are required.

But anyways, initially I just wanted to point out that we even do not do the chosen approach properly. This adds additional confusion imo. At least we should do one approach consistently.

Sanne Grinovero
June 7, 2013, 6:02 PM

Here I highly disagree with you Sanne Grinovero. If we were to agree that the opt level split would be the better approach, then it would make to change. Sometimes disruptive changes make sense and are required.

I agree with you actually The thing is that top split vs. bottom split definitely is subjective - we'll have to agree on that until someone can come with some scientific proof for technical superiority.

When I mentioned "wrong" using quotes, I meant "wrong" from a subjective point of view of one group, as there is no absolute. Sorry I can see how my use if double quotes might not be international style.

Definitely if we were to agree that it's wrong in absolute sense I'd want to fix it of course.

But anyways, initially I just wanted to point out that we even do not do the chosen approach properly. This adds additional confusion imo. At least we should do one approach consistently.

+1 this issue stands, not rejecting at all. Just saying that we might likely make changes there soon anyway, so let's consider it during the 5.0 refactoring as you rightfully labelled it. If you feel the need to drive a discussion on top/bottom package split for 5.0, let's do it on mailing list when the time comes as I don't think it should be restricted to those reading this issue specifically.

Fixed

Assignee

Yoann Rodière

Reporter

Hardy Ferentschik

Labels

None

Suitable for new contributors

None

Feedback Requested

None

Components

Fix versions

Affects versions

Priority

Major
Configure