Thinking About Documentation with Ghost Doc

Back when I had a real job, I ran a software department for a large, multinational heavy equipment department (no, really, I did). As a developer, I put off writing documentation until the project was sufficiently late that my manager would cut the documentation task in order to get the project done on time. As a manager, I kept trying to get my team to start in on their documentation early.

It's not that developers are stupid or lazy (though those are the usual reasons given). Developers know that 80 percent of the documentation that is generated is [never used for anything. Most documentation is a waste of developer's time, and usually at the very time when there is absolutely no time to waste.

More importantly, developers know that they can't trust the documentation. For documentation to be useful, a developer must know that when the documentation was initially generated it was both correct and complete. During subsequent changes to the application, the developer must know that the corresponding changes to the documentation were made, were correct and were complete. Here's the rub: Even if all of that was true, how would the developer know?

Look at another way: Let's say you make a change to some application based on the documentation and things. Let's further assume that things go horribly wrong because the documentation was incomplete or incorrect or not up-to-date. Would your manager accept the reason "Well, it should have worked according to the documentation?"

I didn't think so.

When you look at a member on a class you need to know three things:

• What should be passed to the method
• What will you get back
• What's the relationship between the inputs and outputs

There are some additional pieces of information that are useful (what errors are thrown, what events are raised), but the inputs, outputs and transformation rules are the key issues. Object Browser gives you the first two but doesn't describe the business entities behind the data types. And you don't get the transformation rules.

Ghost Doc VS Toolbo documentation tries to fill in some of those gaps by applying transformation rules to your names and embedding the results into XML documentation. Even if you don't like the results, it certainly gives you a start on creating the documentation you might prefer. You can read the initial review of Ghost Doc here.

Of course, Ghost Doc won't handle generating comments about the code inside your method. But that's alright: documenting the code inside a method is a mistake. When you add a comment all you're doing is creating a second version of your program which may or may not match the "real" version in code. And, of course, when you have two copies of anything, the likelihood is that they will disagree with each other ("A man with two watches never knows what time it is").

More to the point -- and to quote Kernighan and Plauger in "The Elements of Programming Style" -- a comment is of zero (or negative) value if it is wrong. Code should be written so that other developers can read it.

Yet another way of looking at: Doctors bury their mistakes. Architects cover them with ivy. Programmers write comments.

Ghost Doc's transformation rules of its own to convert member names into English-like documentation. A method called "AssignTagToSite", for instance, will generate the documentation "Assigns Tag to Site." You can modify the rules that Ghost Doc uses for this transformation. For instance, many of my classes have a method called NewItem. I added a rule that converts that method name into "Creates a new instance of the " where is the name of the class that the member is part of.

The scary thing is that, after a while, you find yourself generating names so that GhostDoc will generate something that's actually useful. Then you start customizing Ghost Doc's rules so that it's easier to generate member names that Ghost Doc can use. It's kind of fun, actually.

While Ghost Doc is a free tool, you wouldn't know it. The usual "fit and finish" issues that I gloss over in a free package don't exist. Ghost Doc comes with a genuine MSI installation package with real installation options. It also recognizes that you might upgrade to another version of Visual Studio and want to import your previous settings. I do wish there were an option to document all the methods in a class so that I didn't have to do each member individually.

Will Ghost Doc give you all the documentation that you need? No. But it might keep your manager off your back and will impress the heck out of your clients (as long as they don't look too closely).

Posted by Peter Vogel on 04/21/2010