How to Avoid the Surprises in Third-Party Components

Six percent of the defects we found in a recent release of my company’s software were directly attributable to documented but surprising behavior in third-party software. It seems that no component was exempt. We were bitten by surprises in AngularJS, Accusoft, Ui Grid, Entity Framework, and the .NET API. You’ve probably encountered a few surprises in your day, too. How can we stop this from happening?

A surprise occurs when you assume one thing, but reality is another. Usually, our developers’ assumptions were entirely reasonable and the components’ authors had made the same mistake we make most frequently: failing to think like a user.

Here is a simple example. We use UI Grid in our application. It offers a nifty textbox at the top of each column by which the user can filter what he sees. Only rows that match what he has entered will show.

For example, in this screenshot I have entered part of a name, so only rows that match that name remain displayed.

Now suppose you want to filter by the Archive Date in the first column. What would you expect to happen if you were to key in 11/29 in the filter for that column?

Yeah, that’s what I would expect, too, but what actually happened was that the grid became empty!

One of our QA engineers found this and reported it as a bug in our software.

I’m sure you can guess the cause: UI Grid’s filters work by default on the raw data rather than the formatted version. In this case, the raw data from the server were formatted with dashes (11-29-2017) but we used JavaScript’s toLocaleString function to present dates in a consistent format throughout the application, with slashes instead of dashes.

I leave it to you to decide whether UI Grid’s behavior violates the Principle of Least Surprise, but it was certainly a surprise to us.

It is hard to avoid being tripped up by these surprises, but in my experience there is one way to give yourself a fighting chance. Read the manual!

That may seem to be pointing out the obvious, but it’s not what we do, is it? Usually, we “google” for just enough information to let us complete the task at hand and then we move on to the next task. At most, we go through a tutorial that covers only the basics and then we dive in. That’s a great way to learn, but it’s not a great way to avoid the surprises that are in every third-party component.

If your team is going to depend heavily on a third-party component, it might be worthwhile, during the time you’re taking it on board, to have weekly discussions about what you’ve found in the documentation. Maybe each team member could be responsible to bring 5 questions of moderate difficulty to contribute to a quiz. You might decide that the weekly sessions will cease only when everyone gets at least 80% on the quiz.

Good luck!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.