Adding correct documentation for a method

Question

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?

Answer 1

Yes, you should document all the exceptions that a method can throwmethod'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.

Answer 2

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.

Answer 3

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.