Sunday, August 27, 2006

Redemption! Oh Sweet Redemption!

In this entry I am going to comment on the revised document interface.  I have already posted the code for the interface as well as the three classes that the revised interface uses: ReturnStatus, DocumentIndex, and TOCElement.  I am including these as separate entries so that you can have multiple web pages up at the same time.  

 The documentation included in these three classes should go a long way toward helping you to understand what is going on in this revised interface.  However, there are a number of topics that I think need some additional commentary.

First, I've tried as much is possible to substitute specific classes for generic value types.  For example rather than using a string class for the document index, I've created an actual document index class.  As presented, the document index class is simply a wrapper around a string.  If you just look at the executing code, this might look a bit silly.  But if you look at the code as a way of expressing the intent, as a way of communicating to people who follow in your footsteps and look at this code in an attempt to understand it, this works quite well in my mind.  I've done the same thing with the table of contents entry.  There's a little bit more information in this class but my primary motivation for creating the class was to more clearly express the intent of the design.

Second, I've tried to reduce the number of methods and to eliminate any sequencing dependencies between the various methods.  The way that I have done this is to introduce to delegates, one to process an individual table of contents entry and a second to process a paragraph within a specific portion of the document.  There are two corresponding methods that work through the document and invoke these delegates at the corporate point.  In my experience, this is a much less error prone approach.  It does push some of the logic into the interface but the variability in how the data is stored within the individual document justifies the increased responsibility.

Third, I have created a separate class to hold the return status.  It is a personal preference, but I do not like "out" parameters.  I much prefer to have everything come back as a returned result of the function.  This eliminates much of the need for the interface to hold state between calls.  Everything that you could ever want to know, is wrapped up in the return value.  if you need more data to be returned, you can subclass the return status class to add this material.

The actual production-quality document manager interface would be more complicated.  The intent here is not to give you an implementation but rather to point out some of the ways that you can use interface more effectively.


Post a Comment

Links to this post:

Create a Link

<< Home