Every developer knows what it’s like to have to make changes
to an existing application. It is the true test of a developer’s skills to
reverse engineer a previous team’s thinking. One thing that can really hinder
this process is when there’s no documentation and all the developers involved
with the application are no longer around.

So, if developers are aware that even basic documentation
can be helpful, why do we often overlook this task? Most developers I know
admit that they just don’t have enough time to write documentation. However,
this mundane task can actually save you or your fellow developers
time down the road.

Weekly .NET tips in your inbox

TechRepublic’s free .NET newsletter, delivered each Wednesday, contains useful tips and coding examples on topics such as Web services, ASP.NET, ADO.NET, and Visual Studio .NET.

Automatically sign up today!

If you need to write documentation, check out my tips on
what it should include and where to find tools that will assist you in this
process.

Describe an application’s core elements

It can be a bit overwhelming to start composing a document
that outlines the technical details of an application. One way to make the
process less daunting is by first looking at the four core elements that are in
every application: data, business rules, user interface, and security. Here are
more details about each element:

  • Data: The backend data utilized by
    a system can be as simple as a few tables or as complex hundreds of tables
    as well as stored procedures, views, and so forth. An up-to-date data
    model/diagram can save hours of time when faced with a new system.
  • Business rules: Current approaches
    to system design place business rules in their own objects, which are
    separate from the data and the user interface, but this isn’t often the
    case. A simple document outlining a system’s business rules can greatly
    enhance the understanding of what an application actually does.
  • User interface: I think the user
    interface is one of the easier application features to understand,
    primarily because you get a good feel for it by simply loading and using
    the application. Custom controls or third-party tools are often used, so
    the learning curve is often steeper. A good approach to documenting the
    user interface is to provide a list of the forms and other elements
    utilized in the system, along with a detailed description of each.
  • Security: Developers often
    overlook this feature when documenting a system. As you browse through
    existing code, you’ll undoubtedly notice security checks applied in
    various areas, but it is hard to grasp an overall understanding of an
    application’s security model.

Enhance documentation with pictures

It’s easy to enhance the four core elements with diagrams
and figures. Database systems like SQL Server make
it easy to churn out a data model via the Diagrams element within the SQL
Server Enterprise Management client. The Diagrams feature assumes the database
was properly designed (primary and foreign key relationships) so it can
properly identify relationships. If primary and foreign keys are not
appropriately defined, relationships are apparent between the elements, thus
making it hard for the system to generate a helpful diagram. You should use a
tool like Visio
or your favorite word processor to create diagrams for your system as you build
it.

Screen captures are a great way to document the user
interface and provide an overview of a page. You should annotate screen
captures to point out various functions. Tools like AnyDoc
Software’s CAPTUREit simplify the process of
grabbing and working with screen captures.

Unified Modeling Language (UML)
has evolved into the standard for describing a system with its various diagrams
and symbols. UML diagrams include: architecture, sequence, and class.

  • An architecture diagram describes the
    overall system, detailing the various layers of the system and how
    different users interface with them as well as business rules.
  • You
    can use sequence diagrams to
    document processes.
  • Class diagrams outline system
    objects.

While IBM Rational
provides powerful (and expensive) UML tools, you can create UML diagrams using
other products such as Visio.

Insert comments in your code

The most basic form of documentation is code comments. The
.NET Framework uses the Java approach to using XML style comments in C#. Then,
a developer can use a command-line tool to extract these comments and create
basic system documentation of code elements. If the developer properly inserts
comments in the code, it’s possible to extract object relationships from the
comments.

While it’s ideal to insert comments as you develop, it can
also be useful to insert comments when you make changes to the code, in order
to let other developers know what you change and why. These comments are
particularly useful for resolving problems that occur after a code change
(source control can also address that problem).

Check out these commercial tools

Compiling your own document can be time-consuming. There are
various commercial products available to automate the process of documenting
your code. Here are two I recommend:

  • ASP.NET
    Documentation Tool    :     Offers rudimentary code documentation by
    providing a simple snapshot of all code elements from the source. Similar
    items like forms, controls, and such are grouped together. (A similar tool
    is available for SQL Server.)
  • PrettyCode.Print
    for .NET    :     Provides an easy way to generate hard copies of source
    code that are readable. The output is formatted with line numbers and so
    forth.

These tools simply spit out existing code and comments in a
readable format. They don’t (and cannot) insert any comments on the “how
and why” questions developers usually hear when they’re examining an
application.

Other resources

Microsoft’s patterns & practices site has a great
book on building secure ASP.NET applications. It includes various security
model diagrams that you may use as a starting point for documenting your own
system.

You should also check at your favorite bookseller for books
focusing on technical documentation and UML. There is plenty of information
available for those wanting to know more.

Think of your fellow developer

I feel obligated to create documentation when I think of how
much my effort will help another developer do his or her job. Even if you don’t
have time to create as detailed documentation as you would like, a simple
document explaining what the system is supposed to do and why it was built can
go a long way in helping to answer questions and resolve problems in the
future.

Tony Patton began his professional career as an application developer earning Java, VB, Lotus, and XML certifications to bolster his knowledge.

Miss a column?

Check out the .NET Archive, and catch up on the most recent editions of Tony Patton’s column.