Effective Naming Conventions

Modern day development can be one of the most tasking professions around, but without a doubt also one of the most rewarding. Amongst the trialling tasks we must go through each day, one of the most arguably difficult necessities is how we name our types.

This is partly due to the different naming conventions that come into play when using multiple words, underscores, hyphen, camel-case. Though we usually have code style guidelines to enforce a consistent use, this doesn’t really address the original problem.

It can be often overlooked, but naming is essential for the readability of code, how you name your types will later influence how your code is interpreted and understood by your fellow colleagues, and it’s your responsibility to make sure that meaning is conveyed in the best possible way.

As developers we have many tools at our disposal to ensure correct documentation, whether it be through unit test cases, extensive Javadoc, annotations or as I would like to emphasise in this article … effective naming conventions.

One of the methods I prefer to use is to apply logical context to the object or resource in question, and thereby when my colleagues read it, they can accurately assume the behaviour and responsibility. Context is not just a god object we’re forced to use for Android, but it’s the scope, the reasoning for your environment.

Combine effective contextualisation with single responsibility you find that most methods and members can be named with just a single verb or noun respectively. Whilst this is mostly just a play to have an aesthetic class appearance, it has the side-effect of forcing you to think about the responsibility of the code you’re writing.

If you can’t explain it simply, you don’t understand it well enough.
 — Einstein, Albert

One thing to take into consideration is how types are read when reviewing code, rarely would you just look at the name, but in the case of variables one would regard the actual type, meaning you don’t have to reflect the type of the variable when considering its name.

Methods have the additional benefit of arguments and a return type, meaning that there will be even more context provided and you should be able to make a safe assumption on the behaviour of the method based upon its dependencies.

<T> Flowable<T> fromIterable(Iterable<T> iterable) { … }

Iterable seems a little too much iterated here, no?

You can also see from the return type that this method returns a resource based upon the arguments, so ultimately even if the method was named simply named xyz(...), you could safely assume that it produces a Flowable based upon the input of an iterable.

This assumes that dependencies provided through the method signature, are relevant only to this method and effective dependency injection has been performed, see my previous story on effective dependency injection scoping.

This is fairly comparable to most RESTful or RPC endpoints, when referring to a resource action, though the latter will typically combine two words to reflect both the resource and the action. This is a really good example of how context can take much of the hassle out of naming, when you know the resource you’re working with, only since verbs make sense.

tl;dr

Context > Explicitness

A single golf clap? Or a long standing ovation?

By clapping more or less, you can signal to us which stories really stand out.