Exceptional communication in code

How intentional programming and instructive error messages drastically reduce support time.

Customer support concerns the entire company, not just the support department. Developers help support personnel with particularly difficult questions or unclear errors. However, a short question costs a lot more than the two minutes it takes to answer it. The developer needs to get back into the flow he/she was in before the question was asked; that alone easily takes fifteen minutes or more. Productivity suffers if that happens several times a day.

Because of these context switches it is in the financial interest of the company to reduce the dependency of support personnel on developers as much as possible. There are two ways to reduce this dependency: by training support personnel and by improving the software. Training only gets you so far if the software is so unclear that it always requires a developer to know what’s going on. This post focuses on improving the software by making it intention revealing with instructive error messages.

With programming, there’s a difference between the intention (idea) of the code and the way it’s implemented.

With programming, there’s often a difference between the intention of the code (what the developer wants it to do) and the way it’s implemented (what it actually does). When something goes wrong in the code, it doesn’t know about the intention of the developer, so its error message will reflect the implementation of the code. This is where intentional programming and instructive error messages come in.

For example: the intention of a developer could be to update the summary of an item in a Content Management System. The implementation on the other hand gets the list of fields of an item, selects the summary field and updates its content.
If the summary field is not available for the item, the code, not knowing the intention, would throw an error message saying something like ‘could not find the item in the list’. This message is very unclear; it appears to have nothing to do with the intention of updating the summary.
In this case the developer should rewrite the error message saying ‘the summary field is not available, please check the item configuration’. Support personnel, or even the client, understand this message and know what to do about it.

The most naive implementation, completely lacking intention, could be:

public void UpdateField(string name, string content) {
  _fields.First(f => f.Name.Equals(name)).Content = content;
}

If the UpdateField method is called with a name that isn’t in the fields list the code (C#) throws an InvalidOperationException with the message ‘Sequence contains no elements’. That’s not very helpful. A more instructive implementation would be:

public void UpdateField(string name, string content) {
  try {
    _fields.First(f => f.Name.Equals(name)).Content = content;
  }
  catch (InvalidOperationException e) {
    throw new InvalidOperationException(
      string.Format("The {0} field is not available. Please check the item configuration", name), e);
  }
}

Of course, don’t use exceptions for flow control. A short, intention revealing implementation would be:

public void UpdateField(string name, string content) {
  var field = _fields.FirstOrDefault(f => f.Name.Equals(name));
  if (field == null) {
    throw new InvalidConfigurationException(
      string.Format("The {0} field is not available. Please check the item configuration", name));
  }
  field.Content = content;
}

So, when coding, think about your future self, your colleagues and your customers. Write intentional software with instructive error messages.