RE: [e4-dev] Package naming

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

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

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?

I can understand the tendency to use
"internal" as a package suffix in the case where there is a 1-1
correspondance between API and internal packages, but that is often not
the case. What do you do when you have an internal package with no corresponding
API package, or an internal package that provides implementation pieces
for several API packages?  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).

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. Anyway, that's
my $0.03 on that, I'll sit back and see what everyone else thinks.

"Konstantin Komissarchik" <konstantin.komissarchik@xxxxxxxxxx>
Sent by: e4-dev-bounces@xxxxxxxxxxx

02/10/2009 01:11 PM

Please respond to
"konstantin.komissarchik@xxxxxxxxxx"        <konstantin.komissarchik@xxxxxxxxxx>; Please respond to
E4 Project developer mailing list <e4-dev@xxxxxxxxxxx>

To	"E4 Project developer mailing list" <e4-dev@xxxxxxxxxxx>
cc
Subject	RE: [e4-dev] Package naming

I am not a stakeholder in e4,
but I do pay attention to what is happening in the project and I thought
I would add my two cents to this discussion. I agree with John that having
a convention for this and sticking to it is extremely important. I also
agree with Ed that the conventions currently used by the platform are not
the best. Some of the other projects have already moved to the convention
that separates api from internal code as late as possible in the namespace.
This keeps the code together and makes it easier to move it across bundle
boundaries as a unit (merging bundles, splitting bundles, etc.).
 
For instance…
 
bundle id: org.eclipse.fproj.enablement.jdt
 
Packages:
 
org.eclipse.fproj.enablement.jdt
org.eclipse.fproj.enablement.jdt.internal
org.eclipse.fproj.enablement.jdt.libprov
org.eclipse.fproj.enablement.jdt.libprov.internal
 
In fact, I would argue that
when developing a new functional area, even when you don’t immediately
have any plans for API, it would be prudent to reserve location in the
namespace for future API additions. 
 
org.eclipse.fproj.enablement.jdt.something.internal
   <-- shipping in a particular release
org.eclipse.fproj.enablement.jdt.something
  <-- reserved for future api additions
 
The above strategy allows you
to keep co-location API and internal code without moving the internal code
after API is added.
 
Hope this helps the discussion,
 
- Konstantin

Konstantin Komissarchik | Consulting Member of Technical Staff
Phone: +1 425 945 8445 | Mobile: +1 206 898 0611 
Oracle Eclipse Tooling
411 108th Ave NE, Suite 800 | Bellevue, WA 98004

---

From: e4-dev-bounces@xxxxxxxxxxx
[mailto:e4-dev-bounces@xxxxxxxxxxx] On Behalf Of Ed Merks
Sent: Tuesday, February 10, 2009 9:42 AM
To: E4 Project developer mailing list
Subject: Re: [e4-dev] Package naming
 
John,

It's always struck me as unnatural for a component's packages not to be
rooted on the component.  Consider too that in EMF we have components-soon-to-be-subprojects
where the subproject name is effectively two part, e.g.,  emf.compare,
emf.ecoretools, emf.cdo, and so on.  I agree that consistency is nice
though I wonder how the placement of internal creates confusion.  It
seems reasonable to argue that if I'm looking for all the packages of a
component that I can look within its namespace...


John Arthorne wrote: 

The e4 package names don't follow the Eclipse project conventions [1],
or any other convention as far as I can tell. In particular, the position
of "internal" in package names isn't consistent across e4 bundles,
for example: 

org.eclipse.e4.ui.model.internal.application (internal is 6th segment)
org.eclipse.e4.ui.model.internal.workbench
org.eclipse.e4.workbench.ui.internal

Neither of which match the Eclipse convention of:

org.eclipse.<subproject>.internal.<component>.* (internal is
always 4th segment) 

Or the Eclipse 3.x packages:

org.eclipse.ui.internal.application (internal is 4th segment)

There are also some css packages that use "impl" as part of the
package name rather than "internal", presumably for the same
purpose? 

Unlike the test bundle/package names we mentioned earlier, the existing
convention is currently followed consistently across the other Eclipse
projects (org.eclipse.jdt.internal.*, org.eclipse.equinox.internal.*, org.eclipse.pde.internal.*).

The e4 bundles also don't consistently follow the convention that the bundle
id matches the dominant Java package (bundle org.eclipse.e4.ui.workbench
contains packages org.eclipse.e4.workbench.ui.*).

While I'd like to see us revert back to following the Eclipse conventions,
we can discuss picking a new convention in e4 if that makes sense. Ultimately
my main concern is about consistency, as these naming differences create
confusion and are generally impossible to fix after the first release.

Thoughts? 

[1] - http://wiki.eclipse.org/Naming_Conventions#Java_Packages

---

_______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev
  _______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev