• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

The runtime exceptions & the java doc

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

If you know that some methods (may) throw some runtime exception (like ArrayIndexOutOfBoundsException,...) is a good practice to document this ?
I mean in the java doc (method documentation - the @throws flag).

Thanks.
 
mike acre
Ranch Hand
Posts: 197
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Put it this way, it is very bad practice not to.
 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I agree with you Mike.
I come to this because my ide (IDEA 4.5) thinks that this(java doc for "possible" runtime exceptions) is a wrong technique and signals it like an error.
 
Jay Bromley
Ranch Hand
Posts: 48
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello there,

According to How to Write Doc Comments for the Javadoc Tool:
Guidelines - Which Exceptions to Document
Document the following exceptions with the @throws tag:

* All checked exceptions.
(These must be declared in the throws clause.)
* Those unchecked exceptions that the caller might reasonably want to catch.
(It is considered poor programming practice to include unchecked exceptions in the throws clause.)
Documenting these in the @throws tag is up to the judgment of the API designer, as described below.


I know one of the code checkers I've used also complains about @throw tags whose exceptions don't appear in a throw clause. I turned that feature off.

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

This doc (How to Write Doc Comments for the Javadoc Tool - by sun) answers to all my questions.Thanks once more.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic