• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Documenting chained Exceptions ?

 
Ranch Hand
Posts: 435
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
town drunk
( and author)
Posts: 4118
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Wanderer
Posts: 18671
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
With a little knowledge, a cast iron skillet is non-stick and lasts a lifetime.
reply
    Bookmark Topic Watch Topic
  • New Topic