[cosmos-dev] Re: API cleanup standards

[David Whiteman <David_Whiteman@xxxxxxxxxx>]

Bill,

Copying this to the dev list for a broader
audience...

Regarding the placement of "internal"/"provisional"
in package names, the general Eclipse guidelines suggest following the
approach used by DV.  However, I think that it's more reasonable to
push it farther to the right, given that it makes sense to further group
our code by subproject and have internal packages within those subprojects.
 Apparently the Webtools project felt the same way, as noted here:

http://www.eclipse.org/webtools/development/guidelines/naming-conventions.html

"In the WTP
project we are relaxing this convention so that the reserved word may appear
after the fourth component. For example, org.eclipse.wst.xml.tests indicates
test cases that are used for the xml component of the wst subproject. The
prefered usage is to put the reserved names in the fifth position, leaving
the fourth position for the component name."

If you do a Google search of ".internal."
on the eclipse server, it seems that only the core platform code observes
the guideline that "internal" appears in the 4th component of
the package name.  I think it would be useful to create a COSMOS conventions
document and link it from both the API Cleanup page and the dev process
page that lists conventions that we follow that are either not called out
in the Eclipse conventions, or where we are expanding on or deviating from
one of those conventions.

I agree with you that since the "ws"
code is now considered mainstream, and all code not using the new web services
approach has been archived, we should rename those packages/projects/plugins
to remove the "ws" token.

Thoughts from anyone else on either
topic?

David
---
David Whiteman | Tivoli Autonomic Computing
Eclipse COSMOS project committer | http://www.eclipse.org/cosmos/
david_whiteman@xxxxxxxxxx | 919-254-8224 | T/L 444-8224

Bill wrote on 05/12/2008 02:35:15 PM:

> Ali
>         Do we have a naming
convention for our usage of “internal” and 
> “provisional” in our package names for http://wiki.eclipse.org/COSMOS_API_Cleanup?

> Currently Data Visualization seems to use the
org.eclipse.cosmos.
> <internal/provisional>.<subproject>.<…> convention.

> For example:  
>     org.eclipse.cosmos.internal.dr.drs.service.outputter
>     org.eclipse.cosmos.provisional.dr.drs.service.handler.common
> While DC, ME, and RM seem to use the org.eclipse.cosmos.<subproject>.<component>.
> <…>.<internal/provisional>.<…> convention. 
> For example:
>     org.eclipse.cosmos.dc.cmdbf.services.internal.transform.artifacts
>     org.eclipse.cosmos.me.dmtoolkit.j2ee.internal.util
>     org.eclipse.cosmos.me.dmtoolkit.common.internal.artifacts.interfaces
>         Also, now that we
have archived many bundles, we are left with a mixture of
> web service bundles with “ws” in their names (like org.eclipse.cosmos.example.mdr.ws
> ) and other web service bundles without the “ws” (like org.eclipse.cosmos.dc.service.finder).
> Since we have migrated to plain web services, can our cleanup include
being more 
> consistent with our names? 
> Regards
> Bill