• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

How to document right an (run time)exception ?

 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hallo,

I know thet this thema was a lot of time discussed, but, never say never.
My problem is I have a methos m1() and this method uses a method m2(), this method(m2) throws a runtime exception. This exception is documeted in the method(m2) javadoc commentary. Because the method m1 uses the m2 method is possible that the exception from m2 raise.
My question is I must documet this exception also in the javadoc from the m1 metohd ?
IMHO I must do this, becuse if somebody read the api documetation(lets say the tester - the one who wrote the test) must have a clear picture about what the method does (pre and postconditions). Even if I documet the realtion between the methods (somethig like : "method m1 uses m2") is still now 100% clear (at frist/fast overview) which exception are thorwed(you must start you own investigation - see what method are used, see what exception are throwed, think about, drink a cofee, think about, drink a cofee and so on).

Any other opinion ? Comments ?

Regards,
Mihai.
 
Kai Witte
Ranch Hand
Posts: 356
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
hello,

you are absolutely right. Any Exception that can be thrown by a method must be documented. Strictly separate the contract and the implementation, even in your mind. Then it becomes obvious.

Kai
 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
ThanX! I aso found with something in this spirit on "Effective Java" - in the Exceptions chapter(page 181).

Regards,
Mihai
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic