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
