I often come across methods/functions which have an additional boolean parameter which controls whether an exception is thrown on failure, or null is returned.
There are already discussions about which of those is the better choice in which case, so let’s not focus on this here. See e.g. Return magic value, throw exception or return false on failure?
Let us instead assume that there is a good reason why we want to support both ways.
Personally I think such a method should rather be split in two: One that throws an exception on failure, the other that returns null on failure.
So, which is better?
A: One method with $ exception_on_failure
parameter.
/** * @param int $ id * @param bool $ exception_on_failure * * @return Item|null * The item, or null if not found and $ exception_on_failure is false. * @throws NoSuchItemException * Thrown if item not found, and $ exception_on_failure is true. */ function loadItem(int $ id, bool $ exception_on_failure): ?Item;
B: Two distinct methods.
/** * @param int $ id * * @return Item|null * The item, or null if not found. */ function loadItemOrNull(int $ id): ?Item; /** * @param int $ id * @param bool $ exception_on_failure * * @return Item * The item, if found (exception otherwise). * * @throws NoSuchItemException * Thrown if item not found. */ function loadItem(int $ id): Item;
Notes
In case someone is wondering: The examples are in PHP. But I think the question applies across languages as long as they are somewhat similar to PHP or Java.