• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Documenting chained Exceptions ?

 
Tony Collins
Ranch Hand
Posts: 435
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
If a method throws a Exception with another one chained within it, should the chained Exception be documented in the API.
A good example would be the unlock method which throws a SecurityException if the method to be unlocked is not locked and a SecurityException if the lock cookie supplied to it is Invalid.
Tony
 
Max Habibi
town drunk
( and author)
Sheriff
Posts: 4118
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
IMO, no. Chained exceptions are 'bonus' information: I'm not sure you want to tie them to your API documentation.
M
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I get to agree with Max again. Often the whole point of exception chaining is to allow you to decouple the different layers in a system, while still allowing for effective stack trace reporting. Expecting programmers to document underlying exceptions would defeat this purpose. Now, there may be some cases where you wish to volunteer additional info about certain common causes of exceptions; that may be OK. I've never seen a need, but I suppose it could happen. And I'd never make any pretense of having made an exhautive list of possible underlying exceptions - that would restrict options too much later, when you want to refactor the underlying layers. E.g. I might say "One common cause of DBException is a ConnectException, which can often be handled by attempting this operation again after a brief delay." But I'd never rule out the possibililty that it's some other completely different exception.
 
Don't get me started about those stupid light bulbs.
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic