Should a function throw exceptions based on its expected behavior or its goal state?

Question

My coworker and I are debating the correct design for an API. Say we have a function void deleteBlogPost(int postId). What should this function do if the blog post indexed with postId does not exist?

I believe it would be appropriate to throw an exception, because the function should be designed to do one thing. When the user calls a function called deleteBlogPost, they always expect the post with ID postId to be deleted. To try to delete a post with an invalid postId does not make sense, so an exception should be thrown.

My colleague argues that the caller does not really intend to delete a specific post, just to ensure that after the call, the post does not exist. If you call deleteBlogPost with a nonexistent post ID, the goal state is already achieved, so nothing should happen. He also noted that this design ensures calls to deleteBlogPost are idempotent, but I'm not convinced that this is a good thing.

We found examples of both patterns in several APIs. For instance, compare deleting a dictionary/map entry with a key that does not exist between Python and Java:

Python:

my_dict = {}
del my_dict['test']   # KeyError: 'test'

Java:

Map<String, Object> map = new HashMap<>();
map.remove("test");   // no exception thrown

Should a function throw exceptions based on its expected behavior or its goal state?

Answer 1

Should a function throw exceptions based on its expected behavior or its goal state?

Neither. This is a false opposite.

The proper criteria for whether to throw an exception is whether it is due to exceptional circumstances.

Java:

You should only use exceptions for exceptional situations. An exceptional situation is an unexpected situation that is out of the ordinary. A situation is not exceptional just because it's less common than other situations. In a non-exceptional situation you should use return values instead of exceptions.

c#:

Exceptions should not be used to change the flow of a program as part of ordinary execution. Exceptions should only be used to report and handle error conditions.

So the real question is whether you expect the file to be missing and if that is a normal business case, given the context and requirements, or if it is some kind of exceptional behavior that you wouldn't normally expect.

I can think of reasons to do it either way. In a highly parallel system, for example, if it's often the case that several threads are deleting files at the same time, you might want deleteBlogPost to fail silently. On the other hand, if the blog post is a sensitive item and a one-time deletion is required, and the deletion event is logged and auditable, it might be better if deleteBlogPost threw an exception, to ensure data consistency.

Answer 2

If you absolutely must know, right now, this very moment, that the delete succeeded in making something into nothing you can still do it different ways.

One is to throw. Throwing an exception is slow (compared to alternatives). Stack traces don't concatenate themselves for free. Because of this we code monkeys have a tradition of making throwing exceptionally rare. So beware of forcing people to catch, what may be for them, non errors. That may confuse people who are used to the tradition. But this way makes the event hard to ignore.

Another design is to return. This avoids concatenating anything. It just looks weird. People have trouble with the idea of nothing. Getting something when making it into nothing seems strange. But if you must confirm that the nothing used to be something, atomically, then return the something. Let the user put it somewhere safe and test it if they care so much. Done this way exceptions aren't needed and all the same use cases work. It just looks freakin weird.

Since you can't know exactly how your API will be used you have to decide what you will support. If you want to support it all, a name change can make things seem less weird:

Remove a key from dictionary using dict.pop()

dict.pop(key[, default])  

If key exists in dictionary then dict.pop() removes the element with given key from dictionary and return its value.

If given key doesn’t exist in dictionary then it returns the given Default value.

If given key doesn’t exist in dictionary and No Default value is passed to pop() then it will throw KeyError

thispointer.com - Different ways to remove a key from dictionary in python

Now the way it works is less strange and the API users can decide for themselves.

If you absolutely do not care, ever, whether the delete changed anything, so long as nothing remains, you're looking for idempotentcy.

Using pop (with default) will allow an API user to achieve idempotentcy by simply ignoring the returned value.

The relevancy of idempotency (ability to call it repeatedly and expect the same result) is something the API user has to determine. All you can determine as an API author is if it's worth the trouble of supporting that.

Answer 3

Both methods have their pros and cons, and each has situations where it is applicable. I prefer the "no throw" version as this is easier to handle during cleanup. If I try to remove something, I usually don't care if the object was in the container or not; I just want to ensure it isn't in there anymore. If the remover is going to throw if it isn't found, then some types of cleanup code will need to have try/catch blocks and/or check if the object is in the container first. It is also easy to forget to add those handlers or checks, resulting in a cascade of issues when this condition isn't handled.

A third possibility is to have the remove function return an indicator if an object was removed or not. It can be a simple boolean value, or a count of removed objects. This would allow the caller of the remove function decide how to handle the case where the object was not found, without requiring additional overhead in cases where we just want to ensure it isn't there.

Answer 4

There are multiple ways how you can define the outcome of a function void deleteBlogPost(int postId).

• You can define outcome as operation that was performed. Here, this would give the two outcomes post deleted and post not deleted.
• You can define outcome as postcondition. Here, this would give the two outcomes post does not exist anymore and post still exists.

Unfortunately, both definitions are lying to you. They communicate that there are only two possible outcomes and often, developers interprete them as success and failure. You and your coworker fell into the same trap, but you do not agree on what is success and what is failure. The truth is that the function has more outcomes:

• Post deleted.
• Post not deleted because it did not exist.
• Post not deleted because of error (e.g., permission).
• Post not deleted because of another error (e.g., corrupt database).

If you try to categorize these into success and failure, you will always run into disagreements about which category post not deleted because it did not exist belongs to. Unfortunately, the signature void deleteBlogPost(int postId) only leaves room for two categories. It can either succeed or it can fail (via exception). The signature does not communicate that more things can happen.

If you want to communicate correctly, you need to change the function signature. You can, for example, change the return value to an enum with the values POST_DELETED, POST_DID_NOT_EXIST, PERMISSION_ERROR, CORRUPT_DATABASE and remove the exceptions. This way, all outcomes are clearly communicated. However, a disadvantage is that the function may fail silently (because there are no exceptions anymore).

You can keep the exceptions by adding an argument that controls the exception behavior. For example, you can add an enum eExceptionBehavior with the values THROW_IF_POST_NOT_EXISTS and DONT_THROW_IF_POST_NOT_EXISTS (or something more readable). If you call the function like this

deleteBlogPost(42, THROW_IF_POST_NOT_EXISTS);

everyone knows what's going on.

Answer 5

I'll throw in my opinion that both approaches are valid and can be considered correct. The question is which approach fits your needs.

If you treat it as an error, it may help you identify bugs in your application more quickly. However if the situation can result from the normal execution of the program, it creates its own issues.

I recall a very annoying 'feature' of a Oracle driver where it would throw an exception when you attempted to close a connection to the DB when it was already closed. It was something that would just randomly occur every once in a while during the close procedure. There was no real issue, though. The goal was to close the connection and it was closed. Nothing more needed to be done.

On the other hand, if the only way that this situation can occur is due to some sort of programming or execution error, I'd lean towards throwing an exception. It might save you some time debugging.

Answer 6

Exceptions are, as the name already implies, intended to communicate exceptional situations; you could also say "unexpected situations". So the question is:

Is it unexpected that a request is performed to delete a post that doesn't even exist?

Exceptions are not intended to communicate expected failures but it's up to you to decide what is an expected failure and what not.

E.g. if I'd write a HTTP framework, getting a 404 page not found error would be an expected failure to me when trying to fetch a resource as I can impossibly know if the resource exits prior to fetching it. An exceptional failure would be if the TCP connection dies in the middle of the transfer of the resource.

If you say "You must not delete a post that doesn't exist", as that would be a programming error, then trying to do so should throw an exception.

If you say "It is okay to attempt to delete a post that doesn't exist as you cannot even know in advance if it (still) exists", then it would not be an exception if the post doesn't exist, yet it would be an exception if the connection to the database is lost when attempting to delete it as that is not expected to happen.

If you need to know if a post was deleted or not, as the fact that a post couldn't be deleted requires special handling, communicate success/failure:

bool deleteBlogPost ( int postId )

Function returns true if a post was deleted, false otherwise and throws exception if something else went wrong.

Answer 7

It's the goal state. But also...

It doesn't matter

Conceptually, you can think that if you cannot clean up a mess, you need to throw an exception. Cleaning up the mess is as ambiguous as it sounds. But let's make it clear and simple:

• Exceptions are not programming tools. They are knowledge representation tools.

The unfortunate adoption of exceptions as a programming construct can introduce more problems than it solves. So the answer to your question is that it does not matter. Based on what you want to design and model, you decide what you handle and what you don't handle. For whatever it is that you decide to not handle, you must throw an exception. And not only that, you must also inform everyone else using your API that, in those cases, you do throw an exception.

• Code represents instructions. Exceptions represent the lack of instructions.

Whenever you write code, you use signatures for your methods and behavior. These signatures guarantee what someone can expect from you. Exceptions mean that you cannot handle a situation in any reasonable way, based on what you purport you can do. Methods/Functions are not entirely inanimate black boxes. They encode domain knowledge in the form of behavior. Usually, they model a behavior, so the best advice can only come from the modeled domain/behavior. Exceptions were created to make our life easier.

• Our method signatures document what we do. Exceptions supply the complement by documenting what we don't.

But in the end, it doesn't matter. However you design your method, people using your API will get used to it and use it, as you have seen with the various patterns used by different languages. It doesn't matter when or whether you throw an exception, as long as:

• You communicate properly all cases where you may throw an exception (e.g. Java's throws keyword), so that everyone is prepared.
• You provide a fair alternative as soon as you start noticing things like:

try
{
    double x = double.Parse(str);
}
catch (Exception ex) //Or any other exception
{
    //...
}

or

if (dict.ContainsKey(key))
{
    var value = dict[key];
    //...
}

in dozens of locations across a codebase utilizing your API.

Answer 8

It is debatable whether the item not being there can be regarded as success. The caller may believe there is one less item after the call and build on that. Interpreting what the caller really wants or should settle for is speculative. The delete operation failed, period. If that kind of behavior is too rigid for you, call the method TryDelete instead and return a result indicating success or failure.

Because your function does not return a result you should throw. Idempotency is irrelevant in this context.