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
