• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

The runtime exceptions & the java doc

 
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Ranch Hand
Posts: 197
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Ranch Hand
Posts: 48
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
With a little knowledge, a cast iron skillet is non-stick and lasts a lifetime.
reply
    Bookmark Topic Watch Topic
  • New Topic