6.5 Documenting

Documenting

Documentation is a very important part of an application. In fact, it's so important that a lot of European countries require software companies to document their applications by law. I do not favor laws that try to over-regulate and micro-manage, but I can see the reasons for having such regulations. Software is useless unless its features are documented and people know how to use them.

There are three different kinds of documentation: end-user documentation, maintenance documentation and internal documentation. I'll focus on the last one, since this is a book for programmers, but don't overlook the importance of the other two types.

As a consultant, documenting my work is a very important task. I usually help people, write some code, move on to the next project and leave the customer with the code I wrote. The only way to keep this customer happy is to make sure he understands that code so he can use it. Reading and understanding somebody else's code is not trivial, especially when the person wrote the code to do something you couldn't accomplish yourself.

A lot has been written about documenting a programmer's work. I'll try to bring up some new thoughts, rather than repeat what has been written a hundred times.

Comment lines in source code

This is the simplest way of documentation, as well as one of the most effective. It is very informal, too, which means that there is no real process to follow. It's your own decision where to put comment lines and how to describe the code they document. Comments that are valuable for one programmer might be useless for another.

A common way of thinking about it is to comment as much as possible. This is a good start. Nevertheless, the quality of the comments is even more important. Creating a method called "Save" in the "Invoices" class and adding a comment like "This method saves the invoice" doesn't do a lot of good. A comment like this is much more useful: "This method varies from the inherited save behavior because it also saves related line items."

I also like to add more information to my comment lines. Typically, FoxPro comments start with an asterisk (*). I usually add a second character to indicate different kinds of comments. Two asterisks indicate a regular comment:

** We search for the party related to the invoice
SELECT Parties
LOCATE FOR PartyId = Invoice.PartyId

Sometimes, I try to fix bugs or make changes to existing code, but I don't want to delete the old code right away, so I can go back to older versions in case of an error. In this case I use curly brackets:

*{ 06/01/1998 - Changed by Markus
*{ The following line was changed because of
*{ problems due to different field-lengths
*{ LOCATE FOR PartyId = Invoice.PartyId
*{ 06/01/1998 - End of changes
LOCATE FOR Alltrim(PartyId) == Alltrim(Invoice.PartyId)

I have to admit that I simplify this every now and then, and put the *{ only in front of the original line. C'mon, what do you expect? Nobody is perfect

One of my personal favorites is the remark about suboptimal or incomplete code, as in the following example:

*! I have to add some error handling in case the customer wasn't found
LOCATE FOR Alltrim(PartyId) == Alltrim(Invoice.PartyId)

This is a very easy and efficient way to mark parts of code that need more work. I can simply search for every occurrence of "*!" later on. Before I did that, I often wrote code that wasn't quite polished, since it had some loose ends that had to be tied up, but I simply couldn't remember where all those ends were. Now I know what areas need more work, and I also know when I'm finished, which eliminates that weird feeling in my stomach whenever I release a product.

I use a couple other tags as well. Not all of them are generic enough to be used by everyone, but using them as a model you can come up with some tags that you find useful. However, there is one final example I would like to share:

DEFINE CLASS cInvoice AS cItem
PROCEDURE AddItem( lcItemId )
*= AddItem( cItemId )
*= This function allows you to add a new item to the invoice object
*= It requires one character parameter which specifies
*= the item that should be added.

code goes here

ENDDEFINE

This tag allows you to add formal documentation to the source code. I use a utility that scans my source code, takes these tags and automatically puts them in a Word document, which eventually becomes the manual. This makes it easier to keep the manual up to date, because I can run this utility repeatedly to update existing documentation.

Automated comments

The shortcut menu in the Visual FoxPro editor allows you to comment and uncomment single lines or whole code blocks with one mouse click. The standard comments FoxPro creates start with *!* as in the following example:

*!* These lines have been commented by FoxPro
*!* WAIT WINDOW "Hello World!"

As you can see, I use this same notation for code segments that aren't finished and need more work. Fortunately, you can change the way FoxPro indicates comments by adding a simple (but undocumented) entry in the Registry, shown in Figure 1.

Figure 1. You can change the way FoxPro comments code by adding this
entry in the Registry.

All you have to do is add a new string value in the key listed below. The value will be inserted in your code whenever you choose comment in the editor's shortcut menu. Here are the names of the string value and the key:

Key: HKEY_CURRENT_USER\Software\Microsoft\VisualFoxPro\6.0\Options
String Value: EditorCommentString

Description fields

If you use the Visual Class Designer, you can use description fields to document classes, methods and properties. You can define these comments when creating new methods or properties, as shown in Figure 2.

 

Figure 2. Using the Description field to document a new method.

Once created, the description can be modified in the Edit Property/Method dialog, shown in Figure 3.

Figure 3. Modify the description using the Edit Property/Method dialog.

Unfortunately, you aren't prompted for a description when a new class is created, so you need to enter this documentation in the Class Info dialog, as shown in Figure 4.

As discussed earlier, you can also use the Class Browser to edit the description. This is the way I prefer, since the browser allows you to edit all the different descriptions in one place. Furthermore, it seems to be a lot quicker to enter the descriptions in the browser than to use the dialogs that require you to press Apply every time.

I made it a rule for myself to always add a description to properties and methods, no matter what. The same is true for classes. It seems to be an easy task that has a big impact and a lot of advantages.

Figure 4. Enter the description of the new class in the Class Info dialog.

Formal documentation

Formal documentation can be done in many different ways, but using Word seems to be the most common. I like Word because its OLE interface is relatively simple and straightforward, which makes it easy to create and update documentation automatically. I use source code parsers that look for special comment tags, and also a Class Browser add-in, which creates a Word document that describes class structures as well as methods and properties.

Another great way to create documentation for object-oriented applications is by using Microsoft Visual Modeler or Rational Rose. I'll discuss this option in more detail in Part 3 of this book (especially in Chapter 17).

Another issue to consider is the format in which to save your formal documentation. The simple way is to use regular Word documents. Typically, these documents are collected in binders that collect dust on a shelf, and are already outdated at the time of printing, which means they're useless. For this reason I favor something a little more up-to-date, such as online HTML files. These documents are relatively easy to create using conventional tools such as Word. They also make it easy to convert existing documentation from Word to HTML, and allow you to provide your users with up-to-the-minute changes in your documentation.

You might consider creating a tool that starts automatically every night, collects information from class libraries and source code, exports it to Word, saves it as HTML, and uploads it to a Web server. In addition, you could send automated e-mail to inform team members about changes. Hey, wait a minute this sounds pretty cool maybe I could



Advanced Object Oriented Programming with Visual FoxPro 6. 0
Advanced Object Oriented Programming with Visual FoxPro 6.0
ISBN: 0965509389
EAN: 2147483647
Year: 1998
Pages: 113
Authors: Markus Egger

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net