DOSGI - Naming conventions

["A. Rothman" <am...@amichais.net>]

Hi,

In my recent review of the DOSGi codebase, one thing that stood out and 
made the code harder to follow, or at least more annoying, was 
inconsistent variable naming - even for the same types, used with the 
same meaning, within the same class. I'd like to propose to standardize 
on some naming convention so that the code will be more coherent and 
predictable and thus easier to maintain.

I'm not referring to names with added value or meaning in a particular 
context, which have their place, but just the interchangeable and 
generic type names which are by far the majority.

I'm also not advocating any particularly choice of names - any will do, 
as long as they are used consistently.

Here are some quick examples, with the number of occurrences of the most 
common names per type (the stats are not perfect [1], but make the point):

EndpointDescription:
      22 endpoint
      18 ed
      17 epd
      10 sd
       6 ep
       3 endpointDescription

ServiceReference:
      68 sref
      19 reference
      13 sr
      13 serviceReference

BundleContext:
      97 bc
      27 callingContext
      24 context
      24 bctx
      22 bundleContext
      21 dswContext
      10 dswBC
      10 ctx
       7 requestingContext
       2 bundlecontext
       2 bcontext

ServiceRegistration:
       9 sreg
       5 sr
       3 serviceRegistration
       3 registration
       2 reg

ZooKeeper:
      16 zk
       5 zooKeeper
       3 zookeeper

And there are also meaning-specific names, such as Dictionaries used for 
services properties, which are named: props, p, m, config, serviceProps, 
svrProps, etc.

These are just a few types that came to mind, but the inconsistency is 
pretty consistent :-)

Some suggested conventions:

- use the currently most common names: endpoint, sref, bc, sreg, zk, 
props, etc.
- use initials: ed, sr, bc, sr, zk, etc.
- use simple words: endpoint, reference, context, registration, 
zookeeper, props, etc.
- use any combination that seems pleasant to read, e.g.: endpoint, sref, 
context, sreg, zookeeper, props, etc. (this or the previous option would 
be my pick)

Or, we can leave things as they are.

I can do the refactoring if it is agreed to do so.

So how about it?

Amichai

[1]
Here's the quick-and-dirty command I used for the stats:
find -name "*.java" | xargs sed -rn -e 
'/^(.*"|\s*[*]|\s*[/]{2}|.*implements)/! 
s/.*EndpointDescription(<.*>)?\s+(\w+)[^a-zA-Z_(].*/\2/p' | sort | uniq 
-c | sort -nr

Re: DOSGI - Naming conventions

[Christian Schneider <ch...@die-schneider.net>]

On 21.06.2013 01:27, A. Rothman wrote:
> Hi,
>
> In my recent review of the DOSGi codebase, one thing that stood out 
> and made the code harder to follow, or at least more annoying, was 
> inconsistent variable naming - even for the same types, used with the 
> same meaning, within the same class. I'd like to propose to 
> standardize on some naming convention so that the code will be more 
> coherent and predictable and thus easier to maintain.
>
> I'm not referring to names with added value or meaning in a particular 
> context, which have their place, but just the interchangeable and 
> generic type names which are by far the majority.
>
> I'm also not advocating any particularly choice of names - any will 
> do, as long as they are used consistently.
>
> Here are some quick examples, with the number of occurrences of the 
> most common names per type (the stats are not perfect [1], but make 
> the point):
>
> EndpointDescription:
>      22 endpoint 
+1
>      18 ed
>      17 epd
>      10 sd
>       6 ep
>       3 endpointDescription
>
> ServiceReference:
>      68 sref
+1
>      19 reference
>      13 sr
>      13 serviceReference
>
> BundleContext:
>      97 bc
>      27 callingContext
>      24 context
>      24 bctx
>      22 bundleContext
+1 (be careful when refactoring that sometimes we have two 
BundleContexts with different meanings. There we need different names)
>      21 dswContext
>      10 dswBC
>      10 ctx
>       7 requestingContext
>       2 bundlecontext
>       2 bcontext
>
> ServiceRegistration:
>       9 sreg
>       5 sr
>       3 serviceRegistration
>       3 registration
>       2 reg
As the serviceregistration is always for a certain service I propose to 
name it like <ServiceName>Reg. So it shows what service we are talking 
about.
>
> ZooKeeper:
>      16 zk
+1
>       5 zooKeeper
>       3 zookeeper
>
> And there are also meaning-specific names, such as Dictionaries used 
> for services properties, which are named: props, p, m, config, 
> serviceProps, svrProps, etc.
There in general I am against 1 letter names.
>
> These are just a few types that came to mind, but the inconsistency is 
> pretty consistent :-)
>
> Some suggested conventions:
>
> - use the currently most common names: endpoint, sref, bc, sreg, zk, 
> props, etc.
> - use initials: ed, sr, bc, sr, zk, etc.
> - use simple words: endpoint, reference, context, registration, 
> zookeeper, props, etc.
> - use any combination that seems pleasant to read, e.g.: endpoint, 
> sref, context, sreg, zookeeper, props, etc. (this or the previous 
> option would be my pick)
I also favour this or the previous option.
>
> Or, we can leave things as they are.
>
> I can do the refactoring if it is agreed to do so.
>
> So how about it?
>
> Amichai
>
> [1]
> Here's the quick-and-dirty command I used for the stats:
> find -name "*.java" | xargs sed -rn -e 
> '/^(.*"|\s*[*]|\s*[/]{2}|.*implements)/! 
> s/.*EndpointDescription(<.*>)?\s+(\w+)[^a-zA-Z_(].*/\2/p' | sort | 
> uniq -c | sort -nr
>
>
Christian

-- 
Christian Schneider
http://www.liquid-reality.de

Open Source Architect
http://www.talend.com