1) 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 an 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.
2) 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.
3) 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.
4) 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.
5) 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 back and white. In some cases JavaDoc makes really sense and creates value for the maintenance team. Discus within your team when to use JavaDoc. I promise to do this in the future.
Reference: Top 5 Reasons for Not Using JavaDoc in the Next Project from our JCG partner Markus Sprunck at the Software Engineering Candies blog.
You say that “Every developer should be able to read source code and the truth is in the code.” However, you are betraying an arrogance that is common among coders. The truth is not in the code; but in what is “revealed” in the code. If someone doesn’t share your domain knowledge, your coding skills, your coding style, or the jargon you use, then the code is effectively obfuscated to the person reading your code. You reveal very little. Javadoc require formality and some redundancy in the information content of comments. And I will agree with you that an automated… Read more »
I know where you’re coming from — but this position is a little extreme. 5 Reasons why this statement is wrong: “Every developer should be able to read source code and the truth is in the code.” 1. The meaning of the code may only be apparent after reading half-a-dozen interlinked methods, which will take time and derail your workflow. 2. Code can be shared as a jar with easy access to javadoc, but no source code. 3. Java IDEs can show javadoc on-hover, making for efficient working. 4. The javadoc is part of your contract with the user. Having… Read more »