Documenting thrown exceptions.

[dexdyne]

Not strictly php, but this seems a reasonable place to ask 

 

If documenting a routine ( which may or not directly throw an exception ), but whichh calls another one which definitely DOES, how would one write the @throws lines in the procedure header?

 

1. Ignore the exceptions thrown by called routines.

2. Attempt to create and maintain a list of @throws which reflect ANYTHING the routine and its callees can throw.

3. List exceptions thrown by this routine explicitly, and add 

        @throws as fred()

    for each routine we know is called and may throw something.

 

1. Is consistent and easy to maintain, but scarcely useful.

2. Is a maintenance nightmare.

3. Is a slightly smaller nightmare.

 

I guess what is needed is an automated system that scans the routine source but I haven't been introduced to anything of that ilk.

 

David

[hansford]

You can throw errors all day long - don't waste the time. A critical error - DB ect - log it - but there is zero recovery - tell your users - 'hello' is about it. Another less critical-error - ok, continue on with a polite message. But - error checking every thing will just drive you crazy and won't do anything in the end.

Edited January 8, 2015 by hansford

[maxxd]

Personally, I'd go ahead and document the exception with a @throws tag because when another method calls that method, there's a chance it's going to have to catch and deal with the exception the child method throws. I guess there are arguments you could make depending on the visibility or scope of each of the methods, but I like my documentation thorough and have a bit of a tendency to overdo it some times.