Re: [wtp-dev] Naming Conventions issue

[Arthur Ryman <ryman@xxxxxxxxxx>]

Naci/David/Jim,

This topic is very relevant since we
are going to do a refresh of our code soon and we should get the naming
right at that time. I'd like Jim to arbitrate this discussion since WTP
should be a good Eclipse citizen.

However, I am planning to immediately
check in some data code so we can make some progress and I will be observing
the status quo, which is the Jim guideline.

Let's target to have a final resolution
of this by 10/28.


Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063
intranet: http://labweb.torolab.ibm.com/DRY6/

Naci Dai <naci.dai@xxxxxxxxxxxxx>
Sent by: wtp-dev-admin@xxxxxxxxxxx

10/15/2004 07:20 AM

Please respond to
wtp-dev

To	wtp-dev@xxxxxxxxxxx, Jim des Rivieres/Ottawa/IBM@IBMCA
cc	<wtp-dev@xxxxxxxxxxx>
Subject	Re: [wtp-dev] Naming Conventions issue

My 2 cents:

- I would like to identify the subproject and component.  This should
be the primary part.  It allows us to identify packages with as little
assistance as possible.
   org.eclipse.<subproject>.<component>[.*]

- I would like to identify the "api" and "non-api"
as the second part.  The naming conventions suggest identifying non-api
explicitly with reserved words like
org.eclipse.<subproject>.<component>.tests[.*]
- tests
org.eclipse.<subproject>.<component>.examples[.*]
- examples

- Internal non-public packages are best identified in a similar fashion,
but there may be additional keywords that provide applications semantics.
 Here David's principle fits; "appear in
the plugin/package name in a way that best identifies what package or plugin
it corresponds to".:
org.eclipse.<subproject>.<component>[*].internal[.*]
- internal packages



At 12:43 PM 10/15/2004, David M Williams wrote:

Jim, I thought about sending this note just to you for
you insights/purpose in the naming conventions document, but thought I'd
also post to list 
both to see if anyone else had opinions, and also so everyone could profit
from your answer. 



In the Eclipse naming conventions guidelines, http://dev.eclipse.org/naming.html,
it says some reserved qualifiers should come (very) early in the name.
The following package name segments are reserved: 
internal - indicates an internal implementation package that contains
no API 
tests - indicates a non-API package that contains only test suites
examples - indicates a non-API package that contains only examples
These name are used as qualifiers and appear between the subproject
and component name: 
org.eclipse.<subproject>.internal.<component>[.*]
- internal package 
org.eclipse.<subproject>.tests.<component>[.*]
- tests 
org.eclipse.<subproject>.examples.<component>[.*]
- examples 


This rules doesn't make sense to me, and am wondering if I just don't understand
it, or if in fact the rule should be changed. 
I would think the correct statement of the rule should simply be that the
reserved word 
        "appear in the plugin/package name in
a way that best identifies what package or plugin it corresponds to".


Examples you list as "incorrect" seem to follow that proposed
version 
org.eclipse.jdt.internal.core.compiler - Correct usage 
org.eclipse.jdt.core.internal.compiler - Incorrect. internal
should immediately follow subproject name. 
org.eclipse.core.internal.resources - Correct usage 
org.eclipse.internal.core.resources - Incorrect. internal should
never immediately follow org.eclipse. 
org.eclipse.core.resources.internal - Incorrect. internal should
immediately follow Eclipse Platform component name.


Here's some WST examples (I don't know if these will be final names, ...
I just quickly came up with these as examples). 

Now *to me* the first list makes more sense. Are there others readers that
the second list makes more sense? That is, easier to work with?

Names based on what "goes together" based on function

org.eclipse.wst.data 
org.eclipse.wst.data.internal 
org.eclipse.wst.data.sql 
org.eclipse.wst.data.sql.internal 
org.eclipse.wst.data.sql.tests 
org.eclipse.wst.data.tests 
org.eclipse.wst.editor 
org.eclipse.wst.editor.html 
org.eclipse.wst.editor.html.internal 
org.eclipse.wst.editor.html.tests 
org.eclipse.wst.editor.internal 
org.eclipse.wst.editor.tests 
org.eclipse.wst.editor.xml 
org.eclipse.wst.editor.xml.internal 
org.eclipse.wst.editor.xml.tests 
org.eclipse.wst.server 
org.eclipse.wst.server.internal 
org.eclipse.wst.server.tests 

Names following strict rule: 

org.eclipse.wst.data 
org.eclipse.wst.data.sql 
org.eclipse.wst.editor 
org.eclipse.wst.editor.html 
org.eclipse.wst.editor.xml 
org.eclipse.wst.server 
org.eclipse.wst.tests.data 
org.eclipse.wst.tests.data.sql 
org.eclipse.wst.tests.editor 
org.eclipse.wst.tests.editor.html 
org.eclipse.wst.tests.editor.xml 
org.eclipse.wst.internal.server 
org.eclipse.wst.internal.data 
org.eclipse.wst.internal.data.sql 
org.eclipse.wst.internal.editor 
org.eclipse.wst.internal.editor.html 
org.eclipse.wst.internal.editor.xml 
org.eclipse.wst.internal.server 
I'd be the first to admit I may simply be "stuck
in my ways" -- that is, used to seeing it one way -- and don't see
the advantages of always having the name early in the segments, 
so thought I'd post here on wtp-dev to see if others have any preferences
or insights into why one scheme might be better than another. 
Is there a conceptual or working advantage ... or just an attempt to be
over specific on a rule just for the sake of a consistent unambiguous rule?

In either case, it might be nice to spell out the reason for the rule in
the naming conventions document. 

Thanks all. 

Naci Dai,
Managing Director

eteration a.s. 
Inonu cad. Sumer sok. Zitas D1-15
Kozyatagi, Istanbul 81090
+90 (532) 573 7783 (cell) 
+90 (216) 361 5434 (phone) 
+90 (216) 361 2034 (fax) 
http://www.eteration.com
mailto:nacidai@xxxxxxx
mailto:naci@xxxxxxxxxxxxx