Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Java Comments
Java has a special category of comments called documentation comments, and they can be very helpful but also cause problems.
The good part of Java documentation comments is that they have extra structure you can use to your advantage. The Javadoc tool treats the first sentence of the comment as a quick summary of what the class, field, or method is for. This encourages coders to compose a good one-sentence summary of a piece of code. That's good for you as the maintainer; it means that you're less likely to have to wade through an essay on the code.
The problems arise from the formatting. To read them they should be processed through the Javadoc tool and then read with an HTML browser. This means that if you open the source in an editor that's not designed to handle these comments, you encounter something like this:
* The class can be used to define a command line as nested elements or * as a helper to define a command line by an application. * <p> * <code> * <someelement><br> * <acommandline executable="/executable/to/run"><br> * <argument value="argument 1" /><br>
This example is particularly egregious because it's trying to format a code sample, but even short comments can be hard to read:
* Use {@link Project#createTask Project.createTask}
* to create a new Task.
The solution is obvious: You have to run this through Javadoc. This can be inconvenient, since you now have two windows to deal with if you want to read the code. It's also going to be very tricky for you to edit and maintain this comment; you'll need to be able to write HTML as well as Java or C++. The HTML may well set off another round of debugging cycles:
Edit comment.
Run Javadoc.
Read the result in an HTML browser.
Repeat until it looks the way you want it.
A general rule of maintenance applies to Javadoc as well as to your other compilers: Never allow warnings.
If Javadoc complains that you've left out an @throws clause, go back and add it. The reason is simple: The warnings are there to spot suspicious code that could lead to bugs. Complaints from Javadoc are unlikely to signify errors in your code, but they may warn you about situations where the code will be difficult to maintain later.
There's a big difference between getting zero warnings and getting even one warning. Even a single "expected" warning is something that the programmer must remember and deal with every time the compiler runs, whether that compiler is for C++, Java, or Javadoc. Even if you've left a comment in the code somewhere explaining why that warning exists, that's a burden for the maintainer to find, read, and understand the comment.
This injunction holds even if you find yourself having to add nearly meaningless comments like this:
@throws EndOfFileException if the end of file has been reached
This comment is not particularly helpful; the reader is very likely to guess what EndOfFileException means even without that comment. However, there are two practical reasons to include it anyway:
It gives Javadoc a reason to place a link in the documentation to more extensive information on the meaning of the exception.
More importantly, it's one more warning message out of the way. If you can get all of the warnings out of the system, every future time you compile you'll have an extra bit of assurance that you haven't introduced any new, unexpected mistakes.