Developers hate writing documentation. Not all of them, but most do. I don’t necessarily hate it, but neither am I exactly fond of it. I’d much rather be hammering out some sweet code than toiling over a paragraph about what that code is supposed to do. But I am deeply troubled by a growing trend among software developers of eliminating all code commentary, including not writing comments that document the API (eg. JavaDoc, Doxygen).
The “Good Code is Self-documenting” Argument
I agree that most code commentary can be effectively eliminated through judicious application of good variable and method names. As a general rule, if I encounter a bit of code that requires comments for me to understand what it does, it’s a pretty good bet that that bit of code is a candidate for refactoring; it’s also a good bet that the refactoring will eliminate the need for the comments. But “eliminate the API docs”? Come on, now…
There is a school of thought that says, “if you name your classes and methods appropriately, you don’t have to document them.” The only place where this might be true is getter/setter methods that have no other side-effects. While it is true that a properly named method can go a long way toward describing the core behavior, it is virtually impossible for the method name alone to describe all of its behavior.
Take for example the case of the method V put(K key, V value) in the java.util.Map interface. This should be a fairly straightforward method to understand: you supply a key and a value associated with that key, and the map stores the object and key. Simple, right? But what about that return value? Would you know just by the method signature that the Map is supposed to return the previous value associated with that key? What if I pass null in either the key or the value parameters? I assume that’s bad for the key, but I might also assume that null is OK for value — does that fail, remove the old key/value pair, or store null under the key?
Without decent API documentation, the client developer is left to either guess or write experimental code to figure out what to expect. This is no way to treat your users.
The point is this: the method signature is the contract; the documentation is the fine print.
The “Tests as Documentation” Argument
The followup argument to “the code is self-documenting” is usually something like, “There’s no need to document the API, because we have a full suite of unit tests that detail the behavior”.
Let me be blunt about this one: if your position is that you don’t have to tell me how your API works because you’ve made the unit tests available to me, then you’re not fit to be in polite society.
Unit tests are there to verify the behavior, not describe it to potential users of your API. Forcing your users to pore through unit tests is one step above telling them to read the source code. This is no way to treat your users, and should result in having your developer privileges revoked.
Not All Comments are Created the Same
Developers who claim that there should never be a need to write a single comment tend to view the need for comments as some sort of failure of the code. In the case of algorithm implementation, I tend to agree. But this argument loses steam for me in the case of API comments.
There is a fundamental difference between code comments and documentation comments. Code comments are oriented toward the developers/maintainers of the commented code. Documentation comments are oriented toward the users of your library.
The “But the Only Users of My API are On My Team” Argument
Just because your users are coworkers, you think you can treat them like crap? Set the tone. Be a good citizen. Treat them the way you want to be treated. Just because they have access to the source code, does not mean they should be forced to read it in order to understand what it does.
Let’s assume for a minute that you aren’t the altruistic team player that I believe you are… there is another, more selfish reason that you don’t want your users to read your source code: Once they understand the internals of the implementation, they will optimize their code according to your implementation, and you will never be able to change it without breaking applications that depend on that behavior. I’ve seen it happen hundreds of times, and it is always a painful lesson for those involved.
Save yourself the pain and spend the extra three minutes it takes to just write the documentation comment. Everyone will be happier for it.