Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I have method like this:

methodA(someParams)
{
  do some initializations,etc;
  call methodB(someParams);
}

methodB(someParams)
{
  do work;
  if blah then raise exception::FileNotFound
  if blahblah then raise exception::ResourceNotFound
}

When I am adding documentation for methodB, I am also documenting the exceptions it can raise.

But how about documentation of methodA ? It IS consuming methodB that may raise exceptions, so should I still document those exceptions for methodA as well? Right? wrong?

share|improve this question
add comment

3 Answers

up vote 5 down vote accepted

Yes, you should document all the exceptions that a method can throw method's clients are expected to handle. Where exactly the exceptions originate is irrelevant - even if they come from some methodC() which happens to be called by methodB().

Code calling methodA() shouldn't care what other methods it calls in order to get the job done, but it does need know about the things that might go wrong.

In your example, since methodA() doesn't take responsibility for handling the FileNotFound or ResourceNotFound exceptions, any code calling methodA() needs to know that it has to deal with those scenarios.

Now, if methodA() can take some sensible action in the case of a FileNotFound or ResourceNotFound exception, then it should do that and it doesn't need to report those exceptions - it can hide them from its clients.

A simple example, in Java: (For the sake of argument, let's agree that a non-existent file is 0 bytes long)

int getFileSize(String filename) {
    try {
        return getFileBytes(filename).length;
    } catch (FileNotFoundException e) {
        return 0;
    }
}

byte[] getFileBytes(String filename) throws FileNotFoundException {
    // ...
}

Edit

As Illustrated by Bobson's comment, I've feel I've misrepresented a very important point - see the change in bold above!

There are generally 3 cases where an exception/error should thrown:

  1. Things you can reasonably expect to go wrong. e.g. Trying to print something but you can't get access to a printer, or you're trying to open a file which doesn't exist.
  2. Programming errors - i.e. bugs. e.g. Dividing by 0, NullPointerExceptions. These shouldn't be making it into released code so you generally shouldn't be writing code to deal with them.
  3. Unrecoverable errors. e.g. StackOverflowError. These tend to be thrown by the underlying system (virtual machine, OS, etc.) and generally there isn't anything you can do about them.

The ones you should be declaring are those in category 1. Java tries to force you to do this, but it does have some problems.

share|improve this answer
    
thanks, great explanation. –  EricFromSouthPark Jul 10 '13 at 14:18
    
I disagree with this almost completely. Yes, you should document any specifically raised exceptions in the method that raises them, but you shouldn't propagate that documentation to methods that call those methods. That's just asking for out-of-date documentation, significant development overhead, and extra effort. What if you add a new exception 15 methods deep? And it can never be complete because there's system-generated errors too. Instead, you should throw appropriate standard errors, and then catch errors on a level you can handle them. –  Bobson Jul 10 '13 at 14:56
    
@Bobson In that case I encourage you to post your own answer! There's certainly a case for not declaring every single possible exception a method can throw, and I'll add a note about that. –  Baqueta Jul 10 '13 at 15:15
    
Definitely better post-edit. I'd started writing up my own answer, but I didn't get very far before getting distracted. I'm still not in 100% agreement, but it's close enough for a +1 from me. –  Bobson Jul 11 '13 at 13:47
add comment

Imagine that tomorrow you will alter methodA so that initialization may throw an exception. Will you document it?

What if you alter methodA so that it catches one of methodB's exceptions and retries?

I think you should copy-paste the @throws clauses from methodB and keep them current with methodA's state.

One of the advantages is that your IDE will readily show you the complete and correct javadoc of methodA, and you will not have to think or to remember its implementation details.

share|improve this answer
add comment

U catch the exception thrown by method B and take necessary steps in method A. Then if its necessary and inevitable, U can throw a exception of same type or another type from method A and document about that exception for method A.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.