3

When using throws IOException NetBeans shows a warning where the addition of the line @throws java.io.IOException is needed. What is this line used for and is this good practice to use it this way?

gmuraleekrishna
  • 3,375
  • 1
  • 27
  • 45
Scarecrow
  • 53
  • 7
  • 1
    It's for documentation purposes. If someone is reading the documentation of code, for example the JDK API documentation, it gives the developer a place to specify why that exception may be thrown. – Vince Mar 13 '16 at 06:21
  • @VinceEmigh Thank you. This has been very helpful as I am new to programming. I see now how useful the documentation side of programming is. – Scarecrow Mar 15 '16 at 14:50

1 Answers1

7

You can use @throws java.io.IOException to comment your method and generate HTML documentation with JavaDoc. In this documentation you can see that this method may throw java.io.IOException.

For example:

/**
* Method doing something
* 
* @param param1 - for something
*
* @throws {@link java.io.IOException} in some circumstance
*/

It's not necessary, but good practice, document your code like this. It is also good practice to do it for non-checked runtime exceptions, such as IllegalArgumentException, even though you don't typically list them in the throws clause.

And if you document your code like this, you can see good formatted comments in your IDE when using 'Quick documentation lookup' in Intellij IDEA for example or hover on method in Eclipse.

Real example:

@throws java.io.IOException example

Aleksandr Podkutin
  • 2,532
  • 1
  • 20
  • 31
  • This is very helpful and I will be sure to take your advice on documentation. As I am new to programming, I am more concerned about the program itself, rather than the overall components of the program (such as Documentation). I will be mindful in my future work. Thank you. – Scarecrow Mar 15 '16 at 14:58