Intention Revealing Names

Update: A small elaboration of this has been published on the Architects zone at DZone.com.  Read it at http://architects.dzone.com/news/intention-revealing-designs. The value of naming of variables, methods and classes is highly underestimated. Given that code is read more than it is ever written, the readability of your code will get more attention than your original thought process that led you to the code. I will be so bold as to say that the reader really does not care how you arrived at those lines of code. The reader is actually focused on what you mean by the code and not how it does its magic.

Often the problem lies in carrying implementation details into the name of the intention. For example, assume you have designed a social network as a directed graph and you want to find all circles of friends that are in this social network (e.g. Joe knows Mary who knows Peter who knows Joe). Since it's a graph, we can find all cycles in the graph, or closed loops. So, you write code such as:

class ObjectGraph {
  public Collection<CyclicGraph> findCyclicSubgraph() {
	  ...
  }
}

class CyclicGraph extends ObjectGraph {
  ...
}

This does not reveal any intention of finding circles of friends nor does it surface the domain adequately. The same code with intention revealing names just reads better:

class SocialNetwork {
	public Collection<SocialNetwork> findCirclesOfFriends() {
	  ...
	}
}

There's a subtlety hidden in the refactored code. Both the circle of friends graph and the graph of the entire network are of the same type. SocialNetwork is a composite and has the advantage that all operations executed on a composite will yield a composite of the same type as well. In other words, all operations on SocialNetwork will yield another SocialNetwork. That is also intention revealing design as well as a bit of suppleness.

Here's another example. You wish to set a boolean to indicate that an object is dirty in your cache.

public void setDirtyFlag(boolean dirtyFlag) {
	this.dirtyFlag = dirtyFlag;
}

But refactored with intention revealing names, the purpose is now explicit.

public void dirty() {
	this.dirtyFlag = true;
}

public void clean() {
	this.dirtyFlag = false;
}

Whenever you are writing code, ask yourself: "Is my intention clear and unambiguous?" If the answer is "No!" then your code is most probably lacking readability. There are refactoring techniques and many patterns that can be used to increase the suppleness of your design, but just spending a few extra brain cycles on the names that you use in your code can make an enormous difference in displaying your intention and not your implementation. This alone will increase readability and reduce maintenance of your code.