Does 'HTML' in javadoc comments reduce the readability? Is so, what's the alternative? [closed]

Question

Is it a good or bad practice to use HTML in javadoc comments?

When I look at the comments of java methods they all look nicely formatted with the name of method at the top followed by the entire method header, but when I add javadoc to my methods it's hardly readable (I mean the information that pops up when using the autocomplete when writing code).

So I tried adding HTML to the javadoc comments. It looks better, but then when I generate the javadoc and look at the comments in the browser the layout is all messed up.

Also adding the HTML makes my comments hard to read when reading it directly in the code.

Example of my commment:

/**
* <br/>
* <li><b><i>hasChanged</i></b></li>
* <br/><br/><br/>
* 
* <pre>public void hasChanged(boolean changed)</pre>
* <br/>
* 
* This method can notify the observers when a change has occurred in a model.
* <br/><br/>
* 
* The observer can then set the right controls
* <br/><br/>
* 
* @param changed
* <br/><br/>
* Pass true if a model has been changed from it's starting values <br/><br/>
* Pass false if the model has it's initial values<br/><br/>
*/ 

Are there some best practices how to write comments in java so it is nicely formatted and readable from both the javadoc in the browser as reading it directly from the code?

Also are there any guidelines as to the text comments should contain? E.g. Comments for methods should always start with 'This method.." or something.

Answer 1

There's no 'right' answer to your question because it very much depends on what it is you want out of your javadoc work; however, it is good practice to keep the notation in the code itself as simple and uncluttered as possible, so extensive HTML here is inadvisable.

If your aim is to produce a good quality, stand-alone, HTML document; especially if it's documenting a library where the source code is not present, then extensive explicit formatting in HTML in the source is possibly a useful technique.

More typically, and this is my current activity, the requirement is to produce something that is easily readable in multiple places, namely the source code; a standalone document; and in an IDE such as eclipse. The chances of Eclipse producing the same as what you want from your HTML document is low, and thus it is simplest to accept that limitation and keep the formatting minimal. There's a lot to be said for letting the tool do what it does.

Left to it's own devices the tool will produce something in a form familiar to a new user - that, in itself, has considerable 'ease of use' value. Beauty is in the eye of the beholder; your favoured formatting may be ghastly to others.

I'm puzzled by you documenting the method prototype in your comment (the 'pre' line). Let the tool do that, the benefit of the tool is to stop mismatches between manual documents and code, you're just giving yourself more maintenance effort having a manual copy in the comment.

One benefit of keeping the formatting simple is that it makes the source code comments easily readable in-situ. That makes them more likely to be accurately maintained by developers.

If you are working in a team and expecting others to keep up the quality and consistent formatting of the javadoc then, again, using the absolute minimum of formatting makes commercial sense. Getting developers to write meaningful comments at all is difficult enough without getting them to put "br" in the right place as well.

Keeping the formatting simple does mean a little more work on the words of the commentary in order to get across the information you are trying to give in a way that is clear and succinct without the benefit of emphasis. To answer your second question I'd not pad it out with "This method..." etc. A lower volume of text means it's more easily browsed and taken in by the reader.

In summary it's questionable practice to do this (and definitely don't if you are working in a team) for reasons of:

• Readability of source code
• Maintaining consistency and accuracy
• Not having others mess it up and the job coming back to you to fix it (again and again)

Focus on getting the right information into the text. Users will thank you more for that than for what font it is rendered in.

Hope this helps.