How many times have we faced a dark piece of code written by some sectarian guru whose name has long been forgotten in the tides of time?

Maybe this programmer was even ourselves, we don’t even know.

Documentation to the rescue…

Fortunately, that programmer – let’s call him Neo – was careful enough to write documentation for his code:

/**
 * Sorts the elements.
 *
 * @param elements the elements to be sorted
 */
static void sort(List<Integer> elements)

WHAT THE–?!

We all agree that this documentation is as useless as it is laughable. What is even more hilarious is that Neo’s manager forced him to write such documentation only to latter brag that all the code is documented. Real story!

Don’t write donkey documentation. Just don’t. Instead, write documentation that will provide many benefits to yourself and your peers.

Why it is worth documenting methods

Too often methods are poorly documented, if they are at all. When you have to call such a method you have no way to guess what it does or what assumptions it makes. So you look at its implementation, which can be time consuming and cumbersome. You should NEVER do that.

The implementation of a method describes how the method does something, not what it does. The what can usually be implemented in many ways, so the how, i.e., the implementation, can be changed without breaking client code that relies on the what.

If you rely on the how, you become dependent on this particular implementation and all the assumptions it makes. Then the troubles begin when the implementation of the method and its underlying assumptions change.

For example, assume that the implementation of Neo’s sort method handles null values properly. Two months later, a new implementation is shipped (e.g. to improve performance), which does not care about null values because it assumes the client never use them. Can you guess what happens to all client code that didn’t pay attention to null values? Yes, they’re broken. But how could one know that the method was or wasn’t supposed to handle null values?

Writing documentation takes time, or does it?

Before implementing the method, Neo inevitably thought about what the method should do. Yet he chose to save the 5 minutes required to write it down in a few sentences. After all, the method name already hints what the method does.

Then time passes. Neo has to use its own method but doesn’t remember what it does exactly. So he reads the full implementation, as does every developer that wants to call the method or modify its implementation. How long does it take to read and understand the quick sort algorithm in order to reverse engineer what it does and the assumption it makes? Surely more than 5 minutes. And this is multiplied by the number of times a developer has to read it. This quickly sums up to a huge time waste, and the same case occurs for all methods of the code base. Neo’s manager still wonders why it takes so much time to maintain that damned piece of software. Surely he hasn’t read this.

How should Neo have documented his method then? We’ll discover that in a next post!

 

Do you know one of Neo’s incarnation? Are you one yourself? How do you feel about the documentation you read?