Library API Design error returns: nil vs error tuple vs exception

As a library user my vote would be a tuple return in general.

In this case I’d raise an exception for two reasons:

• according to your description, an empty list is a non-domain input (e.g. because avg([]) is undefined)
• library users can easily handle empty list anywhere up in the call stack

In addition, I’d communicate this through typespec, by using [...] or [element_type, ...].

How common is it that people pass in an empty list?

If it is common (and for instance the parameter is expected to often be based on dynamic user input, rather than programmer-written code), I’d use an error-tuple (or maybe a nil, see below), since it is a common error.
If it is very uncommon, (i.e. only occurs in ‘exceptional’ situations, for instance when a programmer mistypes input parameters), I would use an exception, which means that the average user is not burdened with having to handle it.

Using nil only makes sense if there is one and only one(!) way of your function to return a ‘useless value’ result, and if you do not consider passing inputs that produce this useless value an error. This might actually be true for passing in [] to your statistics function. As soon as there are multiple ways to get a ‘useless value’ (for instance if you have a container that might contain nils) then don’t use them, since their meaning becomes ambiguous.

So: Exceptions for programmer mistake, errors for user mistake or context problems that keep you from continuing, nil if there is exactly one, clear, way to get a ‘useless value’.

value | {:error, reason} is definitely a bad idea. Any of the three listed approaches (nil, ok/error, raising exceptions) is better, because they are consistent in what they return.

I agree with @sasajuric - passing in an empty list to a function that doesn’t make sense on empty lists is most probably a programmer error and should just fail. I’d say that the case here is almost the definition of the ArgumentError exception.

Besides what @sasajuric and @michalmuskala concluded I can see an argument being made for nil as return value, as it’s similar to how e.g. sql does handle the situation of empty list as input to aggregation functions.

Doing statistics on empty list usually involves dividing by 0, so raising ArithmeticError exception makes the most sense. You can always provide another version that doesn’t raise exception but instead returns NaN or nil.

It doesn’t make sense to return anything in your case. I’d just do raise(ArgumentError, "cannot calculate average of an empty list").

Thank you everyone for your input! Before the post my hunch was to go with an exception but it somehow also felt wrong. I’ll do that now and raise an ArgumentError as suggested by many of you!

Thanks for being such a helpful bunch!

@xlphs I’d rather avoid that the users of my lib see errors involved with what the library does but rather what they did “wrong” so I think ArgumentError is better

@Qqwy It’s hard to say how often they’ll do it as a library can be used in all sorts of ways imo I think they should never do it/if it can be empty catch it before ideally though. I like your thoughts on the ways to generate “useless values” - thank you!

@sasajuric yup thank you, type spec will definitely be [number, ...], I remember the dialyzer on benchee complaining when I did that though but that just means I need to tune something

I’m coming to this very late!

I’m also interested in returning a nil vs. a tuple in library design.

But to your question, I have another idea: Design the function so that it can only be called with the proper input—a nonempty list:

def stats([x | xs] = values)

If this is a frequent occurrence in the API, you could create a type for NonemptyList using e.g. Domo, and catch the error at compile time.

@dogweather designing it in a way that it can’t even be called with an empty list results in an exception as well (no function clause matching) which leaves the library user to scratch their head even more. From that perspective I think the ArgumentError is superior.

As for Domo, the way I understand it the only compile time checks it does are against the default values of a struct, which makes sense as a full compile time check against non empty list needs a rather well functioning type system which we don’t have (yet).