What Is Your Code Saying?

Developers often talk of “self describing code“. This term is a favorite answer when a developer’s poor use of comments comes into question. Often the answer: “I don’t need to write thorough comments, because my code is self describing.” Ignoring the commenting part of the example, lets dwell further on the “self describing code” claim. So my question is how well does your code reveal it’s purpose?

Let’s take the following example into consideration. Let’s say I need to determine whether data was binded to a control. The control has a property called Description, that will have a value after data was binded to it. So in order for me to determine whether the data binding operation completed successfully I could write the following code:

if ( string.IsNullOrEmpty( controlInstance.Description ) ) { … }

So what does this say about the purpose of the code? Does this line of code clearly tell you that I am actually checking whether the control was data binded? No. That knowledge is hidden away, deep inside my head. Anyone looking at this line of code will immediately be confused as to why I am doing this check. So now I am faced with two choices; I can either put a comment next to the statement, or encapsulate the logic in a property or method that will reveal the meaning of the operation (preferably we should do both). The latter option will make the code self describing, and reveal it’s intrinsic meaning:

/// <summary>
/// Checks if a data source was binded to the control.
/// </summary>
public bool DataBinded
{
get
{
return !string.IsNullOrEmpty( this.Description );
}
}

Our original line of code then becomes: if ( controlInstance.DataBinded ) { … }

Looking at this code, there is no confusion at what I was trying to achieve. We now also have one place where we define the rules that determine whether the control was data binded, so that if it needs to change, we only need to do it in one place.

The point is that there are a lot of things that need to be taken into consideration when writing and structuring source code, such as performance, coupling, inheritance hierarchy, abstraction, patterns and so forth. A very important one that I believe is too often neglected, or forgotten all together, is how well the source code communicates its meaning. In fact, personally I would say this aspect should be of the highest priority. I believe the team paying attention to this aspect of coding, will really reap the rewards once they have to start maintaining the product, especially as the original developers leave, and new ones join  the team. Considering that the maintenance of existing software can account for over 60% of all development effort, and that 70% of the cost of software is devoted to maintenance, I believe that any technique that can help with easing this task is of great importance, especially if it’s something as simple as packaging and naming your code in a clear and concise manner!