Error Handling and Technical Documentation

Denise Wynn
January 26, 2005

One thing you'll notice in a lot of code related articles and documentation are code examples with minimal or no error handling. I do it myself when I'm writing articles - mainly to keep the code examples short and to the point.

Here is an example (in C#) of what I'm talking about:

String userAgent;
userAgent = Request.UserAgent;
if (userAgent.IndexOf("MSIE 6.0") > -1)
{
     // The browser is Microsoft Internet Explorer Version 6.0.
}

This is from the MSDN .Net Framework documentation on HttpRequest.UserAgent. The example code looks ok and many people have probably copied this code and modified it to suit their needs. But what is not obvious from this example is that if no UserAgent is sent as part of the HttpRequest then this code will cause your page to throw an exception.

If the example had been written something like the following it would be much more obvious to anyone looking at it that you need to handle the case that a user agent string isn't part of the request.

if (Request.UserAgent != null)
{
  String userAgent;
  userAgent = Request.UserAgent;
  if (userAgent.IndexOf("MSIE 6.0") > -1)
  {
       // The browser is Microsoft Internet Explorer Version 6.0.
  }
}

This example is still short and the error handling is directly related to the subject matter.

Here is one of the error handling issues that I've responded to several times on various web development forums. Someone will post that they are getting the following error on an ASP.NET page:

Object reference not set to an instance of an object.
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.

Exception Details: System.NullReferenceException: Object reference not set to an instance of an object.

This is usually followed by a code snippet that looks like:

  XmlDocument test = new XmlDocument();
  test.Load(Server.MapPath("mydoc.xml"));

  XmlNode resourceNode = test.DocumentElement.SelectSingleNode("/resource");
  string resourceName = resourceNode.InnerText;

While the ultimate problem may be that the XPath they are using isn't going to return any results the reason they got the error was because they didn't check for the possibility of null being returned when they called SelectSingleNode. Again I think this common problem is the result of many of the examples in documentation not containing much, if any, error handling. The code snippet above looks like a lot of code examples available for XmlDocument.SelectSingleNode. The user might have just cut and pasted the code from some documentation and changed the file name and XPath query to suit their needs.

But how much error handling in technical documentation is enough? I'll use the above example as my base and add some error handling.

  XmlDocument test = new XmlDocument();
  test.Load(Server.MapPath("mydoc.xml"));

  XmlNode resourceNode = test.DocumentElement.SelectSingleNode("/resource");
  string resourceName = String.Empty;

  if (resourceNode != null)
  {
    resourceName = resourceNode.InnerText;
  }
  else
  {
    //handle the possibility that there is no resourceNode
  }

Is that enough error handling in the documentation? This documentation is specific to SelectSingleNode but what about the possible string issues? What about document loading issues?

  XmlDocument test = new XmlDocument();

  if (File.Exists(Server.MapPath("mydoc.xml"))
  {
    try
    {
      test.Load(Server.MapPath("mydoc.xml"));

      XmlNode resourceNode =
              test.DocumentElement.SelectSingleNode("/resource");
      string resourceName = String.Empty;

      if (resourceNode != null)
      {
        //make sure the node wasn't empty
        if (resourceNode.InnerText.Trim().Length > 0)
         {
            resourceName = resourceNode.InnerText;
         }
      }
      else
      {
        //handle the possibility that there is no resourceNode
      }
    }
    catch (XmlException exception)
    {
       //unable to load the xml document
    }
  }

Now we've added some more error handling to the code snippet but it's not really a snippet anymore. I think this is where the developer and the technical writer have to part ways. The developer in me wants to add all the error handling but the writer wants the example to be clean and make a point. Sometimes adding error handling code makes your example look cluttered and might confuse the user. How do you determine when to trade-off readability for sound coding?

Ultimately I think it is the responsibility of the developer to implement proper error handling in their code. But I also think technical writers should consider including relevant error handling when it isn't going to obscure the example.