Is Method Documentation Important?

Is class and method documentation important when programming? In my experience, this is a question for which the industry has no general answer, to some it is and to others it isn't.

Before I started developing professionally, I used to document voraciously: I wrote fully-formed Doxygen comments for every variable, class, and method I added to a codebase, explaining both usage and reasoning. In retrospect, maybe it was overkill. One problem is that I'd always comment immediately after an addition or change, and sometimes this resulted in wasted work when I decided some method, variable, or heaven forbid, class, was no longer needed.

I'd worked with at least a few open source projects and with a few well-known APIs that had given me the impression that some coders were even more dedicated to code documentation than I was. A good example of this is Qt, a framework that probably has some of the best documentation around.

The C# Ecosystem

Upon entering the C# world, I realized that business operate a little differently. I want to say that very little thought is attributed to code docs in business, but unfortunately in the case of many C# shops, the reality is that none is at all. This is at least partly due to the advent of GhostDoc, a tool that deconstructs class/method/parameter names into valid C# comment mark-up, and leaves you with pretty, but utterly superfluous, comments like the following:

/// <summary>
/// Processes the event request.
/// </summary>
/// <param name="eventTriggerCode">The event trigger 
/// code.</param>
/// <param name="agencyVehicleData">The agency vehicle 
/// data.</param>
/// <param name="locationData">The location data.</param>
/// <returns></returns>
private bool ProcessEventRequest(

One of the major problems with this approach is that it's impossible to tell without close inspection which docs were generated from GhostDoc and which weren't. Only comments not generated by GhostDoc are worth reading because GhostDoc comments by definition, provide no more information than is already contained in the documented symbols.

This leads to interesting side-effects when GhostDoc use is widespread. Where I work, GhostDoc is part of the standard developer set-up process, and every developer is encouraged to use it. Thanks to GhostDoc, we've ensured that every variable, method, class, constant, and enumeration in our codebase has docs attached to it; but docs that contain no more information than can be obtained by reading their respective symbol names. The result is predictable: no one reads docs anymore!

On many occasions, I've been asked about some implementation detail in some method I wrote. After answering the question, I refer that developer to the method docs that contained the answer so that they can reference those in the future (I never use GhostDoc). The fact that they never thought to read them in the first place isn't surprising in the least, 99% of the time they would have found nothing there.

Not only could you clarify your source code by removing GhostDoc from your development process, but I'm convinced that you could cut costs by saving several megabytes on your source control server by removing the thousands of instances of the following from your code:

/// <param name="sender">The source of the event.</param>
/// <param name="e">The EventArgs instance containing the 
/// event data.</param>

(Joking)

But what if there's a good reason that comments in C# have lost their importance? Visual Studio makes code navigation so elementary that it's as easy to find and read a method's source as it is to look up its documentation. Maybe C# developers have simply learnt that reading docs is the hard way of doing things.

Haskell

A similar phenomena has occurred in the Haskell community as well, but maybe for a different reason.

The vast majority of Haskell documentation is minimal to the point of absurdity (I'm not complaining, just pointing out a fact). Take the standard XHTML combinator library for example. Giant swathes of data and functions have no documentation at all, and those that do only have a few words. No overall usage information for the library is provided anywhere.

I'm going to say that the poor documentation is mainly due to two things: Haskell's very descriptive type system, and that Haskell developers as a general lot are fairly skilled programmers. My question here is, assuming that my second point has any shred of truth, does that mean that skilled programmers don't consider detailed docs useful?

I Have No Conclusion

I haven't experienced enough diversity in development environments to draw any meaningful conclusions on this topic, but I'll write some up anyway.

There are of course some situations where extensive docs is a no-brainer: any kind of API that will be used by anyone without easy access to your source code, for example, or methods where you're doing something really obscure.

All I can say in general is that it's a pleasure working with codebases with documentation that's well-written and which has obviously had some thought put into it, so I'll continue to document my own code the same way.

Posted on November 5, 2009 from Calgary

Newest Articles