As with any job, programmers should always strive to improve the quality of their work. In programming, there are many loosely-structured “best practice” techniques we can use to write code that is as efficient as possible and easy to update and maintain.
Some are well-known, broad-reaching best practices, like DRY (Don’t Repeat Yourself), and reusable concepts suited to more specific situations, like design patterns. Others are architecture concepts, like MVC (Model-View-Controller). In any case, the key is to know when to use a technique, how far to take it and when to avoid it. In this blog, I want to discuss self-documenting code, which is the practice of favoring clear variable names and function names, as well as other coding practices that make code easy to understand, over excessive commenting.
To illustrate my point, let’s look at an example. Here’s a block of code that finds the lowest value in an integer array. I wrote it in Java, but converting it to any similarly structured language should be trivial.
int l = ints[0];
for(int i : ints) {
if(i < l) {
l = i;
}
}
This could be a lot clearer. The variable names should reflect their purpose. This section of code should also be made into its own function with a descriptive name.
int findLowestInt(int[] numbers) {
int lowestInt = numbers[0];
for(int iterator : numbers) {
if(iterator < lowestInt) {
lowestInt = iterator;
}
}
return lowestInt;
}
That’s much better. Even in this very simple example, the code becomes easier to understand. Breaking chunks of code that complete a single task into their own functions also keeps the code more modular and digestible. Of course in some languages, calling a function incurs overhead, so in those cases you should weigh your options wisely.
Self-documenting doesn’t mean completely comment-free. There are multiple situations where comments may still be necessary. Self-documenting code is about avoiding unnecessary comments by producing code that’s as clear as possible. Unfortunately, some take the idea and run a little too far with it, simply as an excuse to leave out comments altogether. Detractors of the theory are usually arguing against this extreme implementation of the idea, rather than the concepts at the core that encourage better coding on multiple levels. Further, this really only applies to source code. That is to say, if you’re building a library or API or anything that will be used externally, documentation for those using the product, rather than editing the code, is still as important as ever. If that means including structured comments that will be processed by Javadoc or some other documentation generator, so be it.
The biggest pro-comment argument I’ve seen is to explain the why of code, such as why a particular algorithm was chosen over another that would also do the job. I don’t believe it is necessary in every case, but if there are non-obvious reasons for using a particular method that might otherwise seem inferior, it can be useful to provide this information to those who may be working on the code later. For example, if a slower method is chosen because it’s thread-safe or more secure.
When you get down to it, self-documenting code isn’t even really about the absence or reduction of comments. The true point is to make code as clean and clear as possible, which includes removing comments that redundantly explain what the code is obviously doing. Of course, that only works if the code is obvious in what it does, which is really the point. Moreover, bad code with a plethora of comments is still bad code. Conversely, in striving to create code in such a way that very few comments are necessary, the result is code which is cleaner, more efficient, more maintainable and more modular.
