Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[handly-dev] A better naming convention for model *Impl* interface methods?

Greetings handly-dev,

I'd like to propose for community discussion an idea of changing the existing naming convention for model *Impl* interface methods, which as you know are currently all prefixed with "h". Although the existing convention originated quite some time ago (in 0.5 to be precise: and is currently well established, it has been mildly annoying since then -- to me, at least.

It is not a secret that the existing convention is modeled after the one used in EMF, a very successful framework, which gives the approach considerable substance and credibility. So why change something that seems to work? Well, one might say that it looks a bit ugly. By "ugly", one would probably mean that it looks quite unusual, especially for the rest of the Java world, and it mangles the method names, which can hurt readability.

It is also worth noting that compared to EMF, where the naming convention is used for methods that form part of an API for "general clients", in our case it is used only for methods that form part of an API for "model implementors" (or "advanced clients") -- it is the *Impl* interfaces we are talking about.

So, I thought that perhaps using an underscore before the "usual" method name would be a more satisfying approach in the long run? Such as _getName(), _getParent(), _exists(), _isWorkingCopy(), _reconcile(..), etc. Using the underscore as the common prefix for *Impl* interface method names looks like a good fit as an additional marker that the API is not expected to be used directly by "general clients".

Although the proposed convention would somewhat increase probability of a conflict with a user-defined method compared to the existing convention, I think that the probability would still remain (very) low. And although it still looks a bit unusual and still somewhat mangles the method names, it seems to me that it is more palatable and looks "cleaner" in the source code. Please have a look at a branch in the playground repository, where I have pushed a version using the new naming convention:

Hint: it may be worthwhile to look at how the exemplary model implementations have been transformed in this experimental branch. A good example is org.eclipse.handly.internal.examples.javamodel.CompilationUnit.

Is it worth it or not? That is the question. I remain undecided. On the one hand, this is a breaking change, and not a small one. On the other hand, while Handly is still evolving in the 0.x version range, we can afford it, and the current adopters may find it worthwhile in the long run. Since this change would affect each of the existing model implementations, I'd like to ask the interested parties to explicitly cast your vote in response to this message. A mere "+1" would suffice if this proposal is fine with you, but any comments would also be much appreciated in helping me make an informed decision.


Back to the top