Top 5 Reasons for Not Using JavaDoc in the Next Project

BY MARKUS SPRUNCK

The Observation that About 95% of the Comments Give No Added Value

If you have a rule that JavaDoc is mandatory in the project, most of the developers will use a JavaDoc generation wizard (e.g. http://jautodoc.sourceforge.net/). These generated comments are fast and create almost worthless content. But for static code analysis tools like PMD everything looks fine.

Most of the existing JavaDoc descriptions explain the WHAT and not the WHY. Every developer should be able to read source code and the truth is in the code. Comments are in general just needed to understand, why the developer decided to use the current solution. In some cases hints to the underlying concepts of references can be helpful, e.g. design patterns, text book chapters, standard algorithms.

The Use of Assert to Check Valid Parameter is More Powerful than Pure Text Descriptions

Even with 100% JavaDoc and high quality of the descriptions many developers won't read the comments as long no obvious problems appear. For these cases the automatic check of valid input to methods with asserts and/or verify functions helps more. A good example of the use of Asserts is the Spring Framework. An exception during development or testing helps more than a never read comment.

Readability of Source Code Getting Worse

Maybe not the most crucial drawback of extensive JavaDoc is the poor readability. The screen space is limited. This can also be a source for errors, because we are humans and more code on the screen means a better overview.

Over the Time a Lot of Comments Getting Wrong

Lets assume you have perfect JavaDoc comments and some enhancement request, defects or refactoring happens. A lot of comments will not be correct, because nobody took time to update them. This is a really poor situation. What should the developer believe the test in the comment or the new implementation? No documentation is better than an inconsistent or outdated documentation.

Refactoring will be Slower

Refactoring is - in most of the cases - a fast and easy job with the modern development tool support. Updating the JavaDoc is still a manual process which needs a lot of time. This leads to the situation that needed refactoring won't be done because JavaDoc.

Recommendations

• There is more than just black and white. In some cases JavaDoc makes really sense and creates value for the maintenance team.

• Discus with your team when to use JavaDoc. I promise to do this in the future.