Tuesday, August 22, 2006

To Document or Not to Document

A long, long time ago in a place far, far away I once built a document management system using Visual Basic 6.0.  The reason that this is relevant to this blog is that it was the system in which I began the journey to understand how interfaces work and how they should be used.  It is a journey that is ongoing.  When thinking about an example that I could use to illustrate interfaces, I thought back to this first system in which I had used interfaces and realized this would be a good example.

While there were several different related applications that dealt with the management of the documents, the primary application was one that captured fault information from various equipment, performed some analysis of that fault information to determine the suggested "next best action", and drove the appropriate document viewer to present to the maintenance personnel (what we hoped was) the most relevant sections of the maintenance documentation that was available.  What I built was a prototype that eventually became a product.  In the interest of protecting the guilty, I will not tell you much more about the specifics.

The reason that this is interesting is that this was the first time that I had done any serious work with design patterns and object-oriented code.  Those of you who have had some experience with Visual Basic 6.0 are at this point rolling your eyes and saying, you can't possibly use "object-oriented design" and "design patterns" in the same sentence as Visual Basic 6.0.  To some extent I would agree with you, having had an opportunity within the last year or so to go back and build some Visual Basic 6.0 code.  But the reality was that Visual Basic 6.0 did provide the beginnings of some object orientation. 

I believe quite firmly that object orientation is something that occurs inside of the mind.  I think you can do object-oriented programming in almost any language, but some languages make the process a whole lot easier than others.  As an aside, I have been doing some work with COBOL in the last few months and trying to apply an object oriented viewpoint whenever I can.  It is not easy, but it is possible, at least to an extent.

Visual Basic 6.0 gave me the ability to define interfaces and gave me the ability to inherit one class from another.  Because of the variability of the equipment and the variability of the documents controlled by this application, I ended up "inventing" the adapter pattern and the template pattern.  It wasn't until a few years later that I became aware of books that would tell me about these patterns and hopefully speed my development efforts. 

The equipment in question came from many different vendors.  Each of these vendors would supply a maintenance document for that particular piece of equipment.  These maintenance documents came in all sizes and shapes.  There were different physical formats.  There were different viewer packages.  Even when the same viewer was used, there were different document layouts.  We even had to deal with the issue of multiple versions: different installations might have the same type of equipment but the versions would be different and we had to keep track of all that and tie each piece of equipment to the appropriate version of the maintenance manual.

In spite of the differences between the different pieces of equipment, all of the documents tended to follow the same format.  Each document had a title.  Each document had a version identifier.  Each document had a table of contents.  With a little bit of effort, it was possible to map each of the documents into a set of "chapters", which in turn contained a set of "sections", which in turn contained a set of "subsections" which in turn contained a set of "sub-subsections" which in turn contained a set of paragraphs.  In general, we restricted the number of levels in the table of contents to four, even if there were more.  Almost all of the documents had an index in which a word or phrase could be mapped to one or more document sections.

Conceptually, I could "open" a document.  In reality there were a half a dozen different ways by which this "open" operation would be performed.  Conceptually, I could read through the table of contents in a depth-first search, limiting the number of levels I would descend to.  Again, in reality, there were a half a dozen different ways by which this traversal of the table of contents could be performed.  Conceptually, I could position the viewer to a particular chapter, section, subsection, sub-subsection and paragraph. 

What this meant was that I could define a common interface to specify how I would manipulate each of the documents.  I'm going to cover the details of that interface in the next blog entry.  The key discovery for me was that it was possible using interfaces and abstract classes to deal with a variety of documents "at arms length" and thus protect the main body of the application from the variability represented by this collection of design documents.  The interface masked the differences that existed in each of the format-specific document viewers.  That allowed me to write the main body of the application in a common way.  From the perspective of that logic, each of the documents appeared to exhibit the same type of behavior. 

As the prototype evolved, we squeezed more and more of the logic out of the interface.  The interface represented the most essential aspects of the document.  The most important benefit of this "minimalist, arms length" relationship was that we could introduce new documents quite quickly.  We were trying to develop the market and one of things that we would do as part of this market development was to show how quickly we could handle a particular format of a document used by a potential new customer.  All that we had to do was to create an object to handle this new document that implemented the "minimalist" interface, tweak the configuration data to make this new document type visible to our application, and go out and demonstrate the application using one (out of many ) of the potential customers documents.  (One of course had to be quite careful in the one's selection of the document to be demonstrated; a document that was similar in format and viewer application software to an existing document and viewer was to be greatly preferred.)

A "heady" time to be sure.  I do not have access to the source code of this prototype.  That is probably just as well.  I'm sure that I would be quite horrified at the quality of that software.  My conceit is that I have gotten a lot better at this since I built those first fumbling attempts at object orientation.  As is almost always the case, the nostalgia is a whole lot sweeter than the actual reality.  I think it is truly said, "One can never go home again."

tags: , , , , ,


Post a Comment

Links to this post:

Create a Link

<< Home