What is in a Name?

>Variable and field naming can go a long way to making your API more useable. I lost more time than I like to working with IPreferenceStore and particularly the newish ScopePreferenceStore class for working with IEclipsePreference.

The problem is in the naming of the arguments.

ScopedPreferenceStore(context, qualifer)

The java doc for the constructor says:

Create a new instance of the receiver. Store the values in context in the node looked up by qualifier.

Ok, fine, but what does context mean in this case? How about qualifier?

The hint is farther down in the the definitions for the arguments:

context – the scope to store to
qualifier – the qualifer used to look up the preference node

Okay, so with this information, wouldn’t it have been clearer to name the arguments as:

ScopedPreferenceStore(scope, bundleQualifer)

The reason is that to use the ScopedPreferenceStore, code like the following needs to be used:

protected IPreferenceStore doGetPreferenceStore() {
  IScopeContext scope = new InstanceScope();
  String pluginId = XMLCorePlugin.getPluginid();
  ScopedPreferenceStore prefStore = new ScopedPreferenceStore(scope, pluginId);
  return prefStore;
}

The only way I was able to figure this out was by looking at a unit test for the ScopePreferenceStore.

Advertisements
This entry was posted in clean code, eclipse. Bookmark the permalink.

4 Responses to What is in a Name?

  1. Antoine says:

    >No, the qualifier does not have to match the bundle id. It can be anything. It's particularly useful when using chained preference stores, for example, having a development preference store, a testing preference store and a production preference store. In that case, the qualifier is the phase. You can make them depend on each other to get the values from development unless defined and testing, etc.

  2. David Carver says:

    >Then what we have here is not enough Java Doc with the context and the method itself. Which is another problem with writing good API, making sure how a method is implemented or can be used is clearly documented.

  3. Miles Parker says:

    >Great post, David. I think it's really useful for us to call out specific examples in code. One of the great things about Eclipse culture is that people are really respectful of the contributions of others, but sometimes I wonder if that means that we hold back from talking about other contributor's code. I hope we can loosen up on that, because all design choices have elements of the arbitrary and we can all benefit from feedback.I think "Context" is probably one of the most overused names in javadom, and perhaps in the english language. Note that common usage is not the same as over-usage. For example..Names like "Provider", "Descriptor", "Visitor" and so on are good because they instantly let users you know what the pattern they are using.Names like "Polygon", "Invoice" and so on are (of course) useful because they describe what the object is representing. Though sometimes they aren't well enough qualified.Names like "Writer", "Renderer", "Container" and so on are also useful because we know what function they are serving.You know a name isn't so good when it is used for all kinds of completely different things in all kinds of different, um, contexts. If it feels vague when you're naming it, it is definitely going to be vague when someone is using it. Sometimes you can make these work by qualifying them further, but often you could just the qualifier. Here are some more examples — selected at random — that I've run into recently:"Source": Aren't almost all Objects the source of something?"Store": Is that the place I'm actually persisting things, or is it the reference to that place? Then what's this other object called "Resource" doing?"Component": Fine, if you're actually using the Composite pattern, but people hardly ever are."Block": Unless it's a concurrency thing, its some kind of chunk of something else. Probably.."Entry": Where? For what?"Reference": Hey, an object that refers to another one!"Manager": Hmm, something that is responsible for some other thing, right?"Handler": Ok, apparently this is handling something that needs to be handled. I think of this as the all-purpose fudge."Helper": I actually like this one, because here we're openly admitting that we don't know where the hell else to put this functionality.Sometimes, if we're really vague on what we're trying to encapsulate, I think we should just call the class "Thingie" and be done with it.Of course, then there are the favorite Eclipse usages that I use every day but I'm still not really sure what they mean in what (again, that word) context.."View""Viewer""Part""Site""Page"Even these can work out ok if they exist as short hand for an aspect of a system for which we know the context — and there's that word again!The there are the in-betweeners. Here the names can be useful if they're used in a disciplined way, and are appropriate for very abstract framework central objects, but they have been abused so frequently that we might want to look for alternatives especially as we get into the implementation level."Feature": Objects very often represent some kind of aspect or feature of something. But what do we really mean by that?"Action": Well, it's clearly an object that can do something!"Resource": Um, something that exists somewhere probably..I can say all this because I've used every one of these. πŸ™‚ While providing no documentation. πŸ™‚ πŸ™‚ In fact, in some cases they're key parts of an API I've written. I guess sometimes the best we can hope for is to be clear about our ambiguities..

  4. David Carver says:

    >Let's not forget the good old, arg0, and arg1 names we see all too often as well.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s