Coding Peeves

This'll probably be the first in a series of pet peeves in API design. The common thread is that there is value in consistency. This is true throughout application design. Consistency means predictability. Your end users will thank you for sparing them lots of training and headache learning your app. This is even more true for developer users of your APIs. If they have to guess what your black-box methods do, they are wasting lots of very expensive time.

"A foolish inconsistency is the hobgoblin of mediocre programmers" -cdude.

So here is an example of what not to do.

Your API returns an array if there are any appropriate elements, and null if not.

So I have to write this everywhere:

    Widget[] widgets = Utility.GetWidgets();
    if (widgets != null)
    {
        foreach (Widget widget in widgets)
        {
            ...
        }
    }

ARGGH. Here's what the same code looks like if the API returns an empty array:

    foreach (Widget widget in Utility.GetWidgets())
    {
        ...
    }

Am I being lazy? Yes, but that's no excuse for a bad API. Probably a third of all consumers of this API will forget to check for null, even if they are adamant that they should. (I can support this with statistics on projects I have worked on). Your QA department may even forget to try a use case with no appropriate elements. But your users won't forget to try it. And you will be publishing a patch.