Programmers as Channel Surfers

If a program is to be a work of literature, then where does that leave object-oriented programs? In the era of functional decomposition, programs were built around algorithms and data structures. They executed in a single thread as a sequence of steps and subroutine calls, not unlike a story. Our object-oriented programs, on the other hand, don’t have such a fixed path of execution. Whether server or client applications, they start up multiple threads and make heavy use of message passing and asynchronicity. The essence of a program is not in a sequence of steps and subroutine calls but in the subtle relationships between classes spread across many frameworks and subsystems, relationships such as inheritance, aggregation and collaboration. So how does one read a Java application like a story? The whole idea of object oriented programs seems at odds with literate programming.

It may help to view your program less as a novel read in a single sitting and more like a TV show that is tuned in once a week by busy people with short attention spans. The purpose is still to engage and inform, but you need to keep in mind your audience could be jumping in to the story just about anywhere. Like a viewer flipping through channels, happening upon an interesting show, there’s a good chance that the first time a colleague comes across your code is clicking through the frames in a stack trace. They will be debugging an application trying to understand some unexpected sequence of events and will stumble upon one of your classes. Or they might drop in to use some small part of your API. Maybe they jump into your code to extend some capabilities, add a new feature, or make small changes as part of a global refactoring. They just want to know enough to get the task done and keep going. They might watch an episode but then move on.

There are a lot of practical implications to this approach but for this article I’ll just focus on one: give the user the information they need in the context of just “dropping in.” Think about the questions they might have looking at your code in a debugger: What is this class for? What elements are in the collection? Where did this member variable get set? Don’t make them work to find out something you could have made apparent with very little effort to begin with. Your goal is to give them enough information about each element so they won’t have to get sidetracked tracking down other references to the element just to see how it’s used . For example:

• Don’t make it a precondition for them to read a big design document on your intranet just to be able to understand what your GizmoClass is. Put the information as close to the artifact as possible. In the code, or at least in the same directory as the source.
• Document all your classes and interfaces. This may seem like a no-brainer, but it’s not about spending more time writing comments. Instead, keep it as simple as possible. Avoid verbosity and forms. Just a sentence or two to explain what the class is (especially helpful if you couldn’t come up with a really good name). Maybe say what it’s used for. That’s usually about as much as someone needs to know. Refrain from a huge exposition on the overall design or the justification for the class. Save discussion of the class members for the member comments themselves. And if you can’t think of something meaningful to say, don’t say anything at all.
• Don’t duplicate information in an Interface and a Class. If you have to pick one, document the interface. Focus on the interface for describing what something is or represents, and in the implementation, anything noteworthy about the implementation.
• When declaring variables of collection types, if you say nothing else in the comment you should at least state the actual type of the elements of the collection.
• Method javadocs are critical for the casual audience, but not because they will show up in the HTML documentation. Most IDEs will provide javadoc comments in a tooltip or property sheet, saving the user the step of clicking through to the declaration, or opening up the javadocs in a new window.
• Make variable names as descriptive as possible. Not just your member or local variables. People tuning in to your code the first time will have a much easier time decrypting your for loops if instead of i or index you use names like row, month, or customerNumber.
• Consider “Hungarian Notation” for variable names. Many developers find this convention ugly and onerous, but you can’t deny the value of immediately recognizing a variables scope without having to jump to its declaration. There’s a wide spectrum of adherence to this principle; from the old C++ practice of limiting the convention to member variables with a ‘_’ prefix on one hand, to an array of prefixes identifying the scope of every variable.

The point of this is not to enumerate a list of documentation standards for your programs, but to get you to think like an author and empathize with your audience. Use your own experience learning and debugging other people’s code to determine what your audience needs from your documentation. Give them whatever they need to keep them from changing the channel before your program finishes.