I think you are right in one thing: That it all comes down to defining what an exceptional situation is. And, maybe, this is also what makes exceptions hard to use, and quite debated. Some even find that they have no place in a programming language. I guess this is also why I think we won’t agree on this subject :-)

Now, about your example with the coffee shop. Hmm, well a bit far-fetched, I think but okay. If the mocha-master is telling you “sorry we are all out of dark coffee, do you want to wait while we brew more?”, this should then be directly transferable to the Map.get(“foo”) call saying ‘sorry, I am all out of values on key “foo”, do you want to wait for it to appear somehow, from somewhere?” :-)

Happy hacking in Ruby. Now that’s fun !!

It all comes down to defining “exception circumstance”. I don’t think
you can reasonably define that from the application’s point of view,
because that would require a deep understanding of all possible
applications. If you accept that the only thing you are left with is
to use the library’s perspective, which turns out to be reasonably
tractable.

But from that perspective you end up raising a lot more exceptions
because a library does not know, or care, if an application is
going to be able to operate without a configuration item that is
missing or not, it only knows that the application asked for a
configuration item and it is not able to provide that item. It is an
exceptional circumstance because the application would not have asked
for something it did not care about.

As for messy syntax and inefficiency, I suggest that you never let
perceived, or suspected, inefficiencies in the compiler or runtime
impact coding decisions until you have profiles in hand showing that
it actually matters. It almost never does.

Syntax, though is a different issue. But you should think carefully
before you trade try{...} catch{...} for ...; if(){}. There
probably are situations where the second one is much better than the
first but more often than not you are just bring the uncommon/error
path into the main line flow of your code. That usually makes it
harder to understand the intent of the code. Moving the handling
exceptional circumstances (even those that are allowed, or even
expected some of the time, like a missing configuration item) out into
a catch block can have the effect of making the happy path a lot
easier to understand.

In one sense you are certainly correct that a method should do what
it’s documentation says it does. However, I consider that to be a bit
of dodge. Merely documenting the behavior of a poorly thought out
method does not somehow make it good (though that may be the only
viable option for many existing methods).

Most languages don’t good semantics for defining contracts, but that
is OK (maybe even good). We get along just fine in the real world
with out explicit, bullet proof, contracts. For example, when I go
into my local coffee shop and say “give me a cup of dark coffee” I
don’t have an explicit written contract with the person behind the
counter but I would be really annoyed if they just handed me an empty
cup. Of course they don’t do that, they say “sorry we are all out of
dark coffee, do you want to wait while we brew more? That is, they
raise an exception and let me decide what to do with it.

There are a couple of possible definitions of “an exceptional
situation”. I define it as a method not being able to do what the
caller asked. Defining “an exceptional situation” any other way means
that the library author really has to guessing about how the library
will be used, and that never works out well.

It ought to be fairly clear from the method name what is being asked
(that is what we mean by “meaningful names”). A method like get
should not be defined by the comments to mean “return the request
thing unless it rhythms with shoe in which case append ‘… in bed’ to
it and return that”. No, we know that when we say “get” we mean “go
find the thing I am asking about and give it to me”. If the method
cannot do that it should let the caller know that fact so that it can
deal with it appropriately.

If you need method that gets but appends ‘… in bed’ to the value (or
returns some default value when the desired thing does not exist) by
all means have one of those, but be sure to name it descriptively, so
that every one knows what they are getting into.

I do have so say that I find your first example a bit clearer than the
second. However, I think what you really want is a “does a particular
bean exist” predicate, e.g.

if beanHome.beanWithPKExists(PkOfInterest) {
  bean = beanHome.findByPK(PkOfInterest);
} else {
  bean = ...' // create bean here
}

And then probably put block of code in a method like
findOrCreateFooBean(). On the other hand if you have such a method
the first form would be pretty good.

As for annotations, I am not actively writing any Java at this point.
I have in the past and may again in the future but currently I am
using mostly Ruby.

Using exceptions for unexceptional circumstances is considered an anti-pattern in Java. I would much rather have Map.get(“key”) return an ambiguous null and, if the distinction matters to me, use an idiom like if(!map.contains(“key”)) … else value = map.get(“key”); if(value == null) … than be forced to wrap every single Map access in my code with a try/catch block.

Your example may make sense in Ruby (I don’t know Ruby well enough to have an opinion.) It doesn’t make sense in Java. Or perhaps the example was just poorly chosen?

“….Either way my advice is: Do not use nil as a way to indicate that the object was unable to perform the requested operation, that is job of exceptions…..”

I can agree. IFF “..the object was unable to perform the requested operation..” means that the contract cannot be fulfilled. Now, in Java, we cannot always express all we want about contracts, as for example Eiffel can. But, we can do it in javadoc or sometimes by annotations. If, the method is documented to return null if nothing is found on a key lookup in a dictionary (to take your example), then by all means, returning null is the right thing to do. It is NOT exceptional, that the key doesn’t exist or the value is null. In Java, the Map class includes an contains method too.

Now, I then get confused about what you really mean, when you write:

“….Exceptions are not about “exceptional situations”, whatever that means. They are a way for methods tell their caller that it was not able to do what the caller asked it to do. If I say, “dictionary give me the value associated with a particular key” and the key does not exist, the appropriate response is a NoSuchKey exception. Returning a nil in that situation is a lie….”

Cause hell yeahh, exceptions are about exceptional conditions only!! There are just not many programmers that recoqnize this, I think. Even Sun can make mistakes. I have always hated this construct from JEE:

try {
bean = beanHome.findByPK(…);
// update bean here
} catch (ObjectNotFoundException e) {
// create bean here
}

That sucks. I have control logic (is this a create or an update) done with exceptions. Bwadrh! This should be a:

bean = beanHome.findByPK(…);
if (bean == null) {
// create
} else {
// update
}

Have you considered using @Null/@NotNull annotations on methods together with a IDE that can use them for anything?