Clarity is the Prime Directive

To write maintainable code, clarity must be our Prime Directive. It is a given that the code must be functional, but it also must be clear. The code must be understood before it to be can be modified. We cannot change code which we do not understand.

Simplicity is the essence of Clarity
Simplicity is something we all strive for as developers. Why? Because if something it simple, it is easy to understand, and thus, easier to change.

Why do we value many smaller objects over fewer large ones? Because the smaller objects are simpler and easier to understand, their purpose is clear.

If you look at many of the practices we do as developers, you will see that they all function to move the code towards a higher degree of clarity. Granted, there are other aspects, but clarity jumps out at me as one of the most important. Maybe its because in my new position I am working with a lot of legacy code that is not clear…it is very difficult to understand.

Clarity should take precedence
When you find yourself having to choose between clarity and other values, lean towards clarity. For instance, if you are following a consistent domain-based naming convention for your objects, but one class seems to be blatantly clearer if its name violated those conventions. Don’t be afraid to violate the conventions for the sake of clarity. After all, conventions often exist to promote clarity. (Generally following the conventions is clearer, but when this is not the case, choose clarity)

If you are using a 3rd party interface that has a confusing name, you can derive a marker interface from it that gives it a clearer name. This derived interface may seem useless since it provides no new functionality, but if makes your code clearer, use it. Choose clarity over the desire to remove what you feel is useless code.

public interface IVideoCollection : IPoorlyNamedInterface<Video> {}

Naming is important
Given that clarity is so important to coding. It places much more emphasis on smaller, seemingly less-important practices such as using well-chosen names. Naming is one of the most important factors in keeping your code clear and easy to understand.

A name for a method should sufficiently explain what that method does such that the reader does not have to look at the implementation of that method to determine what it does.

There are times where I have debated a name for a single class for over an hour. But the result was worth it. Many times a name I have chosen may seem good for an object, but after a bit of discussion with others, another name emerges that is much better and leads to further insight of the object model. Using an online thesaurus is a good way to get great ideas for names that you may not have otherwise thought of. The right name will result in clarity.

Summary
Clear code is code you don’t have to look at for long to know what it does. It is clear in and of itself. When choosing a solution for a design problem, or choosing a variable or class name, lean towards clarity over other values.