Order Now

Towards Better Code Documentation

By Russel Madere

Many developers, myself included, will say that the greatest problem they have when working on someone else's code is the lack of good code documentation. While there are many arguments, some quite strident, about what is good documentation, everyone can agree that inline comments often provide the best documentation for other developers. However, few of us actually practice this.

On simple projects I often skip documentation and begin coding with little thought and organization. But how many projects stay simple? I, and other developers with whom I have worked, have rationalized not including comments in the code upon which we work. Quotes like "Any developer who knows ColdFusion (or ASP or Python or etc.) can figure out what I mean" or "No one else will maintain this code, so I don't need to comment it" can be heard when discussing why comments were not included in code. Developers must make an effort to add more useful comments.

In his book Code Complete, Steve McConnell made a great deal of this issue. One of his proposed solutions, Program Description Language (PDL), lends itself quite nicely to developing web applications. In this article, I'll explain what PDL is and how you can use it in your development process.

What is PDL?

Like many other documentation methods, PDL advocates plain English comments; what sets it apart is that it advocates including the comments in the actual design process. This means that the code for an application will be fully commented before a single line of code is written.

There are five primary steps to developing a PDL web application: "Gather Business Rules," "Create Application Logic," "Evaluate Application Logic," "Revise Application Logic" and "Code." These can be applied to all web applications, regardless of size, language or utility.

Step 1: Gather Business Rules

This may sound like simplest step, but it is by far the most important. This is where the developer and project manager, if applicable, define the purpose of the application, expected inputs and outputs, and a description of the final product. With many web applications, this step is often an exchange of emails between the developer and customer, but it can also be as formal as a full design document defining everything needed by a developer to prepare a finished product.

This is also the most nebulous step. There are no hard and fast rules here except for completeness, which may vary depending on the developer's familiarity with the design subject. A developer familiar with e-commerce may only need a brief description of the desired shopping cart options to get a complete description of the business rules, while the same developer may require a great deal more information to work on a content management system.

Step 2: Create Application Logic

The next step, "Create Application Logic," should be completed solely by the developer. This is where the developer organizes the business rules into logical sections and breaks the web application into distinct pages or sections. This is when the developer actually starts to create the comments for the code. The project manager may be tempted to become involved at this step, but that is a mistake. Step 2 is where the PDL is actually written. The developer should use plain English phrases to describe the purpose of the planned code, not the code itself. This cannot be stressed enough: Describe the purpose of the code, not the code. Use a comment like "add another user," as opposed to "increment the variable intUserCount." Both comments are valid. However, the first comment describes the purpose of the code much better than the second. While the second comment describes what the code does, it does not express the purpose of the code at all. Commenting with PDL makes the code easier to maintain in the long run, allows the comments to be written in any applicable language and aids in porting the application to another platform, if necessary.

The comments should also indicate any proposed program flow. This is where application logic is introduced. Since the web developer is expected to break the application into logical pages or sections, each page or section can be described as a series of actions, loops and decisions. Indentation, like that used to display logic in the code, can be used. Here is a brief example of the PDL written for a login system used to display a simple menu:

In this example, a description of each step is clearly stated and the logic is indicated by the indentation. In complex applications or sections the logic may be nested deeply. Therefore, it is a good practice to have only one level of indentation in each PDL and to break the complex code out into a function or included section. This will help split the display logic and the business logic into distinct PDL documents. Applying this to the above example would produce:

Segmenting the comments this way accomplishes two things. First, this simplifies the logic of the login section by splitting the menu display into a separate section or function. Second, it makes it possible to change the display without ever editing the main section. This is often useful in complex web layouts where the display may be changed often.

Steps 3 and 4: "Evaluate Application Logic" and "Revise Application Logic"

The third and fourth steps seem like they should be part of the same step, but often a developer will spot a supposed logic error and make a revision only to find several days later that the error wasn't really an error. Other developers or the project manager should be involved in the evaluation as well.

To evaluate the application logic of the PDL, print it out and look at it line by line. This will kill a few trees for large or complex applications, but having a printout allows the developer to make notes and revisions without changing the original PDL. Where the logic seems fuzzy or missing, notes should be made. They will be addressed during the revision step.

The developer needs to be able to defend the logic as defined. If the logic cannot be defended, it should be changed. Also, the developer should have full input in the evaluation process. The notes, were applicable, can become the basis for a larger application description to allow future developers to maintain the code.

Once all of the PDL is evaluated, the developer needs to revise the original PDL. Here the developer needs to be honest and address all issues brought up in the evaluation. He needs to clear up all logic problems and keep a clean delineation between the business rules and the display. Once he has addressed all of the issues brought up in the evaluation, it's time to do another evaluation. The cycle of evaluate/revise should be repeated as often as necessary to produce a complete PDL document.

For large applications, the evaluation/revision can be done on sections of the code. If, however, changes are required in another section, that section should go through an evaluation to ensure the changes will not break the section. This is especially important where global functions are used.

Step 5: Code

The final step, "Code," should now be the simplest step. The developer now needs only to create the code that best does the function described in each step. For the original example, a ColdFusion implementation could be:

The code should complete entire block level elements like the CFIF and CFOUTPUT blocks. This allows the developer to test each piece of code incrementally. In this example, I would have coded the CFSET commands first, then the first CFQUERY, then the CFIF/CFELSE block, then the not validated message, then the second CFQUERY, then the CFOUTPUT and finally the menu option display. Each step of the coding could, and should, be tested as it is completed.

If a logic error is found during the coding, development should stop until the error is addressed, evaluated and the PDL revised. Coding can resume, but most likely, some previous coding will be rendered obsolete by the logic error.

While this is a simple example, it can easily be scaled to large applications. In addition, this example was chosen to demonstrate the simplicity of the PDL method, not to demonstrate a particular coding style or methodology.

It is understood that web applications do not lend themselves to fully separating the display from the business rules. However, advances in object oriented techniques for web development are making this much more possible. Designing web applications with PDL will be simple if the developer is willing to leverage advances in web development languages and design accordingly.

I am not suggesting PDL as a "best practice." It is probably not a best practice for all web development. It is, however, an excellent way to get reasonable comments into pages of code.

---

Russel Madere is the Webmaster and Internet Coordinator for The SunShine Pages (http://www.sunshinepages.com), a New Orleans area independent telephone directory publisher. He has been a web developer for nearly a decade and a ColdFusion developer for over 8 years. Additionally, he has experience in project management and was a FORTRAN developer prior to turning to the web.

del.icio.us | digg | Spurl | Simpy | Newsvine | BlinkList | Furl | reddit | BlogMarks | Yahoo! My Web | Ma.gnolia | Technorati

• Subscribe
• RSS

• Editorial
• Specials
• Community
• News
• Tech and Tags
• Views
• Reviews
• Techniques
• Security
• Best of ColdFusion Talk
• Knowledge Base
• Blog Watch

• Tipical Charlie

Quarterly Update