Win a copy of Design for the Mind this week in the Design forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

declare runtime exceptions in javadoc?

 
Mr. C Lamont Gilbert
Ranch Hand
Posts: 1170
Eclipse IDE Hibernate Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
When writing my javadoc for my api, should I put runtime exceptions in there or not? For instance, in the text of the method I say the object must have been started before this method is called. Is it enouogh to make this statement, or should I go ahead and add a @throws IllegalStateException if object is not started, type of thing!?
 
Akshay Kiran
Ranch Hand
Posts: 220
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
look into the api, there are lots of places where the method detail has a section called Throws which declares the exceptions that the method might throw, not necessarily at compiletime, and they have also mentioned it in the explanation of the method, for example, this method from the Integer class. I think the best example to emulate would be the API docs, isn't it?



[ October 16, 2005: Message edited by: Akshay Kiran ]
[ October 16, 2005: Message edited by: Akshay Kiran ]
 
Layne Lund
Ranch Hand
Posts: 3061
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think it is common practice to document runtime exception with the @throws tags. However, you don't necessarily need to declare them in the throws clause of the method's header.

Layne
 
Adam Richards
Ranch Hand
Posts: 135
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I vote yes, document all the exceptions you throw. Callers can decide whether they want to catch them, assuming they know how to something intelligent with them.
 
Tony Morris
Ranch Hand
Posts: 1608
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
It is mandatory as per Design By Contract, which you are using, inadvertantly ad hoc or not. Would you like me to write a contract that surprises you with undocumented behaviour?

You might instead prefer a throws annotation that either refers to a specification of when the exception is thrown, or states it in English.
For example:



The key point is that you document your contract. English is a substandard specification language, but usually (but not always) better than nothing.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic