RE: [e4-dev] Package naming

[Kevin McGuire <Kevin_McGuire@xxxxxxxxxx>]

Perhaps along the lines of what Ed,
was saying ... one thing I did find unnatural about the project/package
naming when I had to create them for CSS was that I ended up with:

    org.eclipse.e4.ui.css.xxx
   (fine) 
    org.eclipse.e4.ui.examples.css
  (odd)

But the second one I had to do because
"ui" was the component.  However, in practice "css"
is a sub-component of "ui" (e.g. the CSS work can be used completely
independently of the rest of org.eclipse.e4.ui, the people who work on
it are different, all the "css" stuff is deeply interrelated,
etc.).  Logically it's all UI so I didn't want to make it it's own
component and end up with:

    org.eclipse.e4.css

and it's own bucket in bugzilla.  Thus
I'd rather see:

    org.eclipse.e4.ui.css.examples.xxx

and although I don't have internal packages
yet, I'd want them to be:

    org.eclipse.e4.ui.css.internal.xxx

It happens though that there is no way
of representing that in bugzilla.  So my claim is, we effectively
have subcomponents but because some of our tools don't allow us to represent
them, we choose not to represent them in places we can, like our project/package
structure.  

I'm not sure that's the right trade
off.  Instead, we could say that subcomponent are realized as:

    org.eclipse.e4.<component>.<subcomponent>.xxx

and in bugzilla as 
    [subcomponent] Some bug
description

which I think matches more closely the
reality.  Btw, I'm only suggesting a single level of subcomponent.

Regards,
Kevin

PS. Like John, I prefer keeping <internal>
more leftward in the naming pattern.

John Arthorne/Ottawa/IBM@IBMCA
Sent by: e4-dev-bounces@xxxxxxxxxxx

02/10/2009 02:07 PM

Please respond to
E4 Project developer mailing list <e4-dev@xxxxxxxxxxx>

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

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
_______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev