Visual Basic 2005 Design and Development - Chapter 13 doc

With this last-minute approach, even if you finish writing code on time, the users may not be able toactually use the application until a month or two later.Many developers and project m

Part III Development

In this Par t:

Chapter 13 Documentation Chapter 14 Development Philosophy Chapter 15 Coding Standards

Chapter 16 Bug Proofing Chapter 17 Testing Chapter 18 Deployment

Chapter 12, “Attributes and XML Comments,” explains how you can use attributes and XML ments to provide some automatic documentation for an application That provides a nice startingpoint, but the result is hardly ready for customers to use The XML comments are combined into anXML document that includes the XML comments surrounded by tags to indicate their purposes.You still need to do a lot of work to turn this into a user-friendly resource

com-There are also many kinds of documentation that don’t naturally fit in XML comments Because theyare in the code, XML comments tend to explain what the code does and how it works, rather thanhow the user can use the application

This chapter complements Chapter 12 by discussing kinds of documentation that you should vide for an application It explains in high-level terms the types of documentation that you shouldprovide It also explains how you can automatically turn the collected XML documentation into amore usable form

pro-Documentation T iming

Many developers leave documentation for the very end They write and debug the application,often going past their original scheduled release date, and then slap together some documentation

at the last minute The result is usually poorly organized, badly written, and incomplete

It is also too late to allow enough time for training If the application is complicated, users mayneed a week or more of training If the number of users is large, or if all of the users can’t dropwhat they’re doing for training at the same time, you may need to run several training sessions atdifferent times, so the whole process may take a month or more The trainers leading the trainingsessions will probably also need several weeks to learn the system well enough to teach the users,and to develop training materials

With this last-minute approach, even if you finish writing code on time, the users may not be able toactually use the application until a month or two later.

Many developers and project managers are happy enough to meet their deadlines and send an application

to the users, even if it doesn’t have documentation In the short term, meeting deadlines is important, but ifthe result is an angry mob of unhappy customers, your reputation as a builder of high-quality software can

be irreparably damaged Even in the short term, you may not gain much by releasing a program withoutdocumentation if you are then flooded with technical support calls

A much better approach is to write documentation continually throughout application development.The initial project specification forms the start of the documentation As system and other high-leveldesigns are written, they are added to the body of documentation Use cases, Unified Modeling

Language (UML) diagrams, lower-level design, and other development documents are also added,

so the amount of documentation grows as development progresses

Visual Studio lets you associate documentation with a programming project Open the Project menu,

select Add Existing Item, and select the documentation file that you want associated with the project Now you can double-click the file in Project Explorer to open it.

If the project is large, it will probably be broken into pieces so that developers can work on different

pieces at the same time Associating the appropriate documentation with each piece makes it easier for a developer to find the relevant files to read about the design or to update the documentation You’ll still need to store higher-level documentation that deals with more than one piece of the application sepa-

rately, but this technique works well for lower-level developer documentation.

Many of these documents are used by developers to guide programming, so writing them not only laysthe foundation for good user documentation later, but it can also have big payoffs during development.Good documentation gives the developers a common vision that they can use to guide development

It allows developers to make the same assumptions so that they can work on their pieces of code whilestaying in synch with other programmers

As the work continues, developers will find mistakes in the designs and correct them That will mean thatthe documentation will also need to be updated To preserve the project’s history, you should place thedocumentation in a revision control system such as Visual Source Safe (VSS) just as you do with code.When the documentation is modified, you should check the appropriate document out of the revisioncontrol system, update it, and check in your changes

If, for some reason, you don’t have a revision control system, you can save snapshots of the documentation each time you make a change One way to do that is to email the revised documentation to yourself or to a special documentation account This is less efficient than using a revision control system because those

systems typically only save the differences between different versions of a file, rather than the entire new

version, but disk space is relatively inexpensive these days.

You may also want to use revision marks when you modify the documentation so that you can see what has changed from version to version If you follow this approach, you may also want to accept all

changes when you create a new version of a file so that you only see the changes since the previous sion It’s pretty hard to find a particular change if a document contains hundreds of changes made over

ver-a one-yever-ar period.

If you use iterative prototyping or another development approach that requires frequent changes to thedesign, the project’s documentation will change a lot during development Continually revising the doc-umentation can seem frustrating to developers who would rather be writing code However, revising thedocumentation provides another opportunity for developers to mentally review the design Often, refor-mulating the design in documentation can help developers discover unanticipated problems, and it canlead to a better design.

Sometimes large projects have dedicated technical writers who specialize in writing user documentationand training materials Writing documentation early and keeping it up-to-date can help technical writersimmensely This is particularly true for military projects, government projects, and projects in otherorganizations that have rigidly defined development processes

Frequent changes to the documentation can be even more frustrating to technical writers than it is to opers, partly because the writers may not see the need for some changes You may need to remind themthat the changes are driven by customer requirements and design needs, and that they are not as arbitrary

devel-as they may seem

Translating changes in the developer documentation into changes in the user documents and trainingmaterials is much easier if you use a revision control system Then you can compare revision dates to seewhich design documents have changed since the user documents and training material were revised.Revision control systems such as VSS can also display the changes to a document so that you can figureout what has changed in the documents and make the corresponding changes

Word processing applications such as Microsoft Word also have revision tracking capabilities In Word, you can turn revision tracking on by selecting the Tools menu’s Track Changes command Then you can easily see the document’s entire history and find changes quickly Unfortunately, Word shows all changes, not just those since a specific date, so it can be hard to find the most recent changes in a document that changes frequently If you save new copies of the document after each change, perhaps in your revision con- trol system, then you can use a difference tool to see what has changed between two versions To compare to documents in Word, select the Tools menu’s Compare and Merge Documents command.

In some development approaches such as staged delivery and some agile methods, development maynever end Instead, the program keeps evolving to adapt to new conditions and requirements In thosesituations, the documentation must also evolve to match

The short cycle times often used by these approaches can make it hard to keep the documentation date If an agile project releases a new version of the program every three to four weeks, the time needed

up-to-to update the documentation can be a significant fraction of the up-to-total time for each release

Although keeping the documentation current is difficult in these sorts of frequent-release projects, it isparticularly important If the application’s features change monthly, the users must have reliable docu-mentation so that they can figure out how things should work on their current version of the program

It is also important that you label the documentation so it is obvious that it matches the current release.You should use the same numbering system for the documentation and the program Program version2.1.12 should come with documentation 2.1.12 The users should also be able to easily find the programand documentation version numbers so that they know they are working with the right documentation.It’s extremely frustrating to be doing exactly what the documentation says, but still get the wrong resultbecause you have the wrong version of the documentation

If users may be working with different versions of the software, matching numbering systems will greatlysimplify support When a user calls with a question, the support engineer can ask for the program’s ver-sion number, and then use the corresponding documentation to find the problem.

Documentation Types

An application should include several different kinds of documentation You can group them according

to their target audience: users and developers

User Documentation

User documentation is intended for use by the application’s eventual users This includes those who willactually use the program on a regular basis, and those who are involved in specifying and designing theapplication It includes the executives who approve and monitor the project, and the “power users” whohelp determine its functionality It also includes trainers who will teach the users and support engineerswho will answer the users’ questions when they use the program

The following sections describe some of the types of user documentation that a typical project mightneed What the project actually needs varies, depending on such factors as how large the application is,the number of users, and how formal the development effort is

For example, I’ve worked on simple projects designed for two or three users where the user manual was good enough for training I’ve also worked on projects designed for use with several hundred users where trainers developed a full-blown curriculum.

Overview

The overview document provides a high-level description of the program’s purpose and operation An

executive summary describes the program as succinctly as possible More detailed sections describethe application’s environment, other systems that it interacts with, who the users are, and so forth.This document should focus on high-level ideas, rather than the program’s specific implementation andusage Typically, this is a relatively short document of one to ten pages

Sometimes the overview is included in the specification, but it’s also useful to be able to pull it out togive to executive-level readers who don’t need all of the detail provided by the specification

Specification

The specification provides a detailed description of exactly what the program should do It focuses on

how the program helps the users perform their tasks without explaining how the program works Thisdocument is updated throughout application development, so it is often called a “living specification.”Specifications are often extremely detailed and can be very long If you use iterative or agile techniques,the specification usually grows over time, so it can be quite long by the time the application is finished

I’ve worked on projects with specifications ranging from one or two pages to several hundred pages.

Use Cases

These are scenarios that describe how the program lets a user perform a specific task They describe thetask, expected inputs and results, and the exact steps that the user needs to perform to accomplish the task.Often, use cases are included in the specification and help define the application’s requirements It isalso useful to be able to pull them out so that users, developers, and testers can test the growing applica-tion to see whether it handles the use cases

User Manual

The user manual describes every part of the application from the user’s point of view It may include

tutorials that introduce new users to the application and tutorials (or “How-To’s”) that explain how toperform specific tasks, possibly those described by the use cases

The user manual should use an instructional approach, much as a textbook does, so that the user canread the chapters in order to learn about different parts of the system The user should not need to jumparound to read about specific topics After reading the manual, a typical user should be able to use theprogram reasonably competently The manual may also include sections describing advanced conceptsand techniques

Usually, the user manual should not include the full detail provided by the specification The tion is designed to let developers and customers decide whether the application does what it should.The user manual is designed to help end users learn how to perform their day-to-day tasks

specifica-Help Files

The help files explain parts of the system to the users while they are running the application The help

should describe each form and dialog in the application Ideally, the forms and dialogs should provide

a way for the user to open the corresponding help page

The help for a form or dialog should explain the purpose of every control that it contains Obvious trols such as a First Name text box only take a short sentence to describe Though it may seem excessive todocument every name, address, and phone number field, it’s easy to write descriptions of these, and it’seasy for the users to skip them if those fields don’t confuse them A simple statement such as “The cus-tomer’s billing address street number” can also be quite helpful when the user can’t figure out whether anaddress is for billing, shipping, the customer contact, or something else

con-Controls that are more complicated or confusing need longer descriptions A good description of a plex topic can save you technical support calls

com-Don’t be afraid of describing seemingly obvious facts in some detail Users only look at the help whenthey are confused and they don’t find the form obvious Users are rarely offended by help that is toodescriptive They are much more irritated by incomplete help

An annotated screen shot of a form or dialog can tie controls to their descriptions concisely.

Often, the user manual is included in the help system so that the user can easily review its material andsearch for tutorials that show how to perform specific tasks It may still be useful to provide a separateprinted version of the user manual, however, so users can read it away from their computers

Context-Sensitive Help

Context-sensitive help provides help based on the controls with which the user is interacting For example,

if the focus is in a street address field, the user might press F1 to view the help for that field either in ahelp file or in a popup window This information is probably duplicated in the main help file describingthe form containing the field

In Visual Basic, you can display a help button in the form’s title bar When the user clicks this button, thecursor changes to an arrow with a question mark If the user then clicks a control, Visual Basic raisesthe control’s HelpRequestedevent and the program can display appropriate help for the control

A control’s HelpRequestedevent is also raised if the user presses F1 while focus is in that control.Figure 13-1 shows the HelpButtonexample application You can see the question mark arrow cursorhovering over the First Name text box

Figure 13-1: When you click the help button in the title bar,the cursor changes to a question mark arrow

The following code shows how this example works This example stores a control’s help string in its Tag

property When the form loads, the program sets a HelpRequestedevent handler for each of the form’scontrols The HelpRequestedevent handler simply displays the control’s Tagproperty

Public Class Form1

‘ Add a HelpRequested event handler to every control

Private Sub Form1_Load(ByVal sender As System.Object, _ByVal e As System.EventArgs) Handles MyBase.LoadFor Each ctl As Control In Me.ControlsAddHandler ctl.HelpRequested, AddressOf Control_HelpRequestedNext ctl

End Sub

‘ Display help for the clicked control

Private Sub Control_HelpRequested(ByVal sender As Object, _ByVal hlpevent As System.Windows.Forms.HelpEventArgs)

‘ Get the control

Dim ctl As Control = DirectCast(sender, Control)

‘ Display the control’s Tag property

Dim txt As String = DirectCast(ctl.Tag, String)

If (txt Is Nothing) OrElse (txt.Length = 0) ThenMessageBox.Show( _

“Sorry, there’s no help for control “ & ctl.Name, _

“Help”, MessageBoxButtons.OK, MessageBoxIcon.Information)Else

MessageBox.Show( _txt, _

“Help”, MessageBoxButtons.OK, MessageBoxIcon.Information)End If

End SubEnd Class

Example program ResourceContextHelp(available for download at www.vb-helper.com/

one_on_one.htm) shows another approach that stores help strings in the project’s resources.

When the user clicks the help button and then clicks one of the controls, the event handler builds the name

of the resources that should contain the control’s help string It uses My.Resources.ResourceManagertoget the resource string and displays it if it exists

Unfortunately, Visual Basic ignores the form’s HelpButtonproperty if either the MinimizeBoxor

MaximizeBoxproperty is True That means you can only display the help button on forms that not be minimized or maximized In many applications, that basically means the dialogs.

can-Pressing F1 while a control has the focus still raises its HelpRequestedevent even if the help button

is hidden, so you can still provide this kind of help on forms that have Minimize or Maximize buttons.

The HelpProvidercomponent provides another way to display context-sensitive help Figure 13-2 showsthe HelpProviderexample program using as HelpProvidercomponent In this figure, I clicked the helpbutton and then clicked the State text box The HelpProvidercomponent displays the help in a popup

Figure 13-2: The HelpProvidercomponent displays help in a popup

To use a HelpProvider, add a HelpProvidercomponent to the form To display a simple string for acontrol, set the control’s HelpStringproperty that is added by the component For example, if yougive the HelpProviderthe name hlpFields, each control on the form gets a new property called

HelpString on hlpFields If you set this string, the HelpProviderautomatically displays it when theuser requests help

For other features provided by the HelpProvidercomponent, see the online help

Tooltips provide a tiny amount of additional documentation for the user They are unobtrusive, so

experi-enced users can ignore them easily If you forget what a field is for, you can hover the mouse over thefield to see the tooltip

To give a control a tooltip, add a ToolTipcomponent to the form and then set the control’s ToolTiperty added by the component For example, if you give the ToolTipcomponent the name tipFields,every control on the form gets a new property named ToolTip on tipFields

prop-After you set the controls’ ToolTipproperties, the ToolTipcomponent displays the tooltips cally Figure 13-3 shows example program TooltipHelpdisplaying a tooltip for the City text box

automati-Figure 13-3: The ToolTipcomponent displays tooltips for controls

Users who have vision impairments rely heavily on tooltips The screen readers used by these users

depend on tooltips to help the user understand the application better.

Training Materials

The type and amount of training materials needed for a project vary widely, depending on the complexity

of the project and the number and types of users A simple project designed for use by one or two userswon’t need much in the way of training materials The user manual and an hour’s time with the projectmanager may be enough For a complicated project intended for use by many users, training mayinvolve a week or more of detailed instruction and hands-on study with handouts, slide shows, demon-strations, catering, and hotel rooms

Often, the training materials will cover much of the same material included in the user manual Itshould include an overview, basic instructions for using the application, and some specific examples

It may include hands-on exercises that let the users experiment with the application on their own withthe instructor present to lend a helping hand

You can make that sort of hands-on training easier if you plan for it from the beginning In particular, youshould try to design the application so that it can easily work with test data that students can destroy with-out affecting real operations Training users on live production systems can be difficult and dangerous.While the training materials may be based largely on the user manual, much of the material may need to

be rewritten to work in a classroom setting

Building effective training materials is an art in its own right Unless you have a special talent for teaching,

or you have a fairly simple application and small user population, you’ll probably be better off leaving this

to a dedicated instructor

Support Materials

Support materials include tools used by support engineers to help users solve problems For a simple

application, this may be nothing more than the user manual and some additional notes For a more plex application, it might include tables of steps to follow when trying to resolve a problem, or even aseparate application that helps guide troubleshooting

com-Historical Documentation

In a long or complicated project, customers, managers, designers, and developers make a huge number

of decisions Sometimes the same issues are faced repeatedly To avoid wasted time making the samedecisions over and over again, possibly in contradictory ways, you should keep a project history thatdocuments every decision made during the project’s lifespan

You should update the project specification to record important decisions, but it’s important to have arecord somewhere of all of the little decisions, too One method for storing this information is to copy allproject emails into a special History account Later, if you face the same problem again, you can searchthat account’s emails for messages that deal with the same subject

Developer Documentation

User documents are often used by developers, too For example, the specification determines what theprogram should do, so it guides the design The use cases describe how the program should handlespecific scenarios, so they guide development and provide tests that developers can use to see if the pro-gram does what it should

In addition to the user documentation, developers need extra documentation that is geared towarddevelopment tasks These are described more fully in Chapter 2, “Lifecycle Methodologies,” so theyare described only briefly here

Specification

Although I listed the specification as a user-oriented document earlier in this chapter, it’s so important to

developers that I’m listing it again here, too The specification is the final word in what the applicationshould do, so developers should be very familiar with it If the program doesn’t do what the specifica-tion says it should, either the program must be fixed, or the specification revised

High-Level Design

High-level design documentation describes how the major pieces of the application fit together It includes

architectural and platform decisions, and describes the application’s biggest systems

System-Level Documentation

Whereas high-level design explains how the application’s major systems fit together, system-level design

explains how the systems work This may include UML diagrams, flowcharts, and other process ing diagrams, as well as text

model-Often, each system can be built as a separate Visual Basic project For example, the main user interfacemight be one project that links to the other system built as separate DLLs In that case, you may be able

to link each system’s documentation to its project as described earlier in this chapter by using the Projectmenu’s Add Existing Item command

Module-Level Documentation

Module-level documentation describes a particular source code module This includes descriptions of

rou-tines that are accessible outside of the module, and descriptions of the code used within the module

If you use the design-by-contract methods described in Chapter 3, “Agile Methodologies,” you shoulddescribe the contracts satisfied by the routines in the module

Higher-level documentation for the module can be included in separate documents This might include

an index of public routines available within the module and the contracts they provide

Other more-detailed documentation is usually included as comments within the module’s code Differentdevelopment organizations often have standard formats that they want for this type of documentation.The following code shows a standard format for describing the module as a whole:

To make using the comments easier, you can turn them into code snippets as described in Chapter 8,

“Snippets, Macros, and Add-ins.” You can download text and snippet versions of these comments at thebook’s Web page

Inline Comments

In the long term, one of the most important kinds of documentation for developers is the inline comment.

Comments give extra context to help developers understand what the code is doing Developers whodon’t understand precisely what the code is doing before making changes are very likely to break thecode, so this kind of documentation is absolutely essential

During the time I’ve been programming, I’ve seen many projects with insufficient comments On oneproject that I helped write, we added extensive comments to the code to explain exactly what the codewas doing We placed comments on key lines to give developers general information Then we addedadditional comments to almost every line explaining exactly what the code was doing in excruciatingdetail These extra comments were far to the right, so they were not normally visible; you could only seethem if you scrolled to the right.

After writing this application, we transferred the code to another corporate organization for long-termmaintenance That organization had the philosophy that any comment that wasn’t essential to under-standing the code must be distracting, so they removed all of our secondary comments and some ofthe main comments A few months later, they discovered that they couldn’t maintain the code becausethey couldn’t understand it Somehow, they never made the connection that they didn’t understand itbecause the comments were gone

That same organization determined a project’s budget based on the number of lines of code Because the count didn’t include comments, it implicitly discouraged their use A developer was rewarded for writing inefficient code that used lots of extra unnecessary steps, but not for writing comments that were critical for maintaining the software.

Since then, I’ve met other developers who shared this “if it isn’t necessary, it’s distracting” philosophy.The problem with this idea is that most code is obvious when you understand it If the code and its com-ments are well-written, it should be obvious how the code works At that point, it’s easy to think thecomments are unnecessary and remove them Unfortunately, when someone else reads the code, orwhen you look at it again later, the code may be far less obvious and the lack of comments can be disas-trous It’s much better to have too many comments and then ignore them when you don’t need them.Another project I worked on included about 65,000 lines of Visual Basic code and practically no com-ments The application was several years old and pieces of it had been written, rewritten, and rewrittenagain in everything from Visual Basic 3 to Visual Basic 6 The many rewrites and the lack of commentsmade huge sections of the code practically incomprehensible The only way to figure out how someroutines worked was to step through them in the debugger Making even simple changes to the codesometimes took a week or more, and had a high probability of introducing a new bug

Add extensive comments to your code Add more comments than you think are really necessary Ofcourse, you don’t need to be intentionally stupid about it The following comment doesn’t add anything

to a developer’s understanding of the code:

index += 1 ‘ Increment the index

Add plenty of comments, but try to add a new perspective that isn’t blindingly obvious from the codeitself

One technique that I often use to comment code is to write the comments first Start with the tion for a routine and break it down into a series of steps that you need to perform to accomplish theroutine’s tasks Then break those steps into smaller steps Continue the process until it’s easier to writethe code than to further refine the steps Now, place apostrophes in front of the text you’ve written tomake them comments and fill in the code

specifica-This type of code reads very differently from code written with the more typical comment-last approach.With the usual approach, you read the code and then use the comments to try to figure out what the

code is doing With the comment-first approach, you read the comments and then verify that the codedoes what the comment says it does Just as it’s easier to select a command from a menu than it is to type

in a command from memory, it’s easier to verify that code does what it should than it is to deciphercode with insufficient context

XML Documentation

Chapter 12 explains how you can add a new type of comments to your code An XML comment beginswith three single quotes (‘’’) Within the comment, XML tags define various sections of documentation.The comments must be well-formed XML code (aside from the single quotes)

The following code shows XML comments for a Personclass:

‘’’ <summary>

‘’’ Represents a customer or employee

‘’’ </summary>

‘’’ <remarks>Use a Manager object for managers.</remarks>

Public Class Person

When it builds an application, Visual Basic automatically gathers these comments and puts them in anXML file The following code shows the resulting XML code for these comments:

<param name=”letter_text”>The text of the letter to be printed.</param>

<param name=”priority”>The letter’s priority 1 = Highest.</param>

<remarks>Use this routine to generate a letter for a person

The routine prints the letter on the default printer andthen waits for you to load an envelope in the manual feed beforeaddressing the envelope.</remarks>

Custom XML Tags

In addition to predefined tags, you can add tags of your own to the XML comments That means youcan store all of the information described earlier in this chapter in XML comments instead of normalcomments For example, you can add history tags to record changes to a module

The following code shows the XML comments on the Employeeclass The Historytags include three

Changeelements that record some changes

‘’’ <Change By=”Rod Stephens” Date=”4/1/2007”>Initial creation.</Change>

‘’’ <Change By=”Rod Stephens” Date=”4/3/2007”>Added comments.</Change>

‘’’ <Change By=”Zaphod” Date=”4/13/2007”>Deleted confusing stuff.</Change>

Example program XmlTestClasses(available for download at www.vb-helper.com/one_on_one.htm)uses several new tags to store additional information The following list shows some of these new tags,plus some others that you might want to use:

❑ History— Contains a series of Changetags recording changes

❑ Scope— Gives the item’s scope (Public, Private, and so forth) The XML document does notinclude this information by itself

❑ SeeAlsoSection— Makes a section to hold seealsotags You can include seealsotags inany other XML comment section, but Microsoft hasn’t defined a specific section to hold them.The intent of SeeAlsoSectionis to give you a place to put the seealsotags, probably at theend of the other comments

❑ Method— Explains how a routine works

❑ Inputs— Describes a routine’s input parameters

❑ Outputs— Describes a routine’s output parameters

❑ Errors— Describes errors that a routine might generate

❑ Exceptions— Describes exceptions that the routine might throw and how to fix them