About Markus Sprunck

Markus Sprunck works as senior software engineer and technical lead. In his free time he maintains the site Software Engineering Candies and experiments with different technologies and development paradigms.

Top 5 Reasons for Not Using JavaDoc in the Next Project

JavaDoc is an absolutely must for the development of frameworks and libraries which provide a public interface for others, e.g. Spring Framework, JDKs. For in house enterprise software and/or product development there are for me the following reasons to ignore the ’100% JavaDoc Policy’ in the future.

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.

Related Whitepaper:

Bulletproof Java Code: A Practical Strategy for Developing Functional, Reliable, and Secure Java Code

Use Java? If you do, you know that Java software can be used to drive application logic of Web services or Web applications. Perhaps you use it for desktop applications? Or, embedded devices? Whatever your use of Java code, functional errors are the enemy!

To combat this enemy, your team might already perform functional testing. Even so, you're taking significant risks if you have not yet implemented a comprehensive team-wide quality management strategy. Such a strategy alleviates reliability, security, and performance problems to ensure that your code is free of functionality errors.Read this article to learn about this simple four-step strategy that is proven to make Java code more reliable, more secure, and easier to maintain.

Get it Now!  

One Response to "Top 5 Reasons for Not Using JavaDoc in the Next Project"

  1. Dan Azlin says:

    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 comment generator is counter productive. But, if the developer will put some care into his/her commenting, the resulting API documentation — and the readability of the code — is enhanced.

    Remember that javadoc exists because there is a need for sufficient information about the code to fix it when it breaks, modify it when needs change, keep it going long after the original developers are gone, and (hopefully) profit from the investment in the intellectual property that it represents.

    Think about how difficult a task it is to reverse engineer the code from an old and undocumented application. If you have never done it, take my word for it when I say that it is a massive undertaking on a par with Sisyphus pushing his big rock up that hill in Hades.

    Also, you need to understand that the reason documentation is so often ignored is that so little care is made is creating good documentation in the first place and keeping it up to date as the code evolves. The fault is in the sloppy developer who disdains the need to comment his work and activly tries to sabotage the documentation by ignoring it and “trash talking” its usefulness. And there is the project/business manager who wants to ship the finished product yesterday and under budget, so don’t “waste time on documentation.” If equal effort were put into improving the comments/documentation, everyone would benefit from a more efficient, easier to debug and maintain product.

    That’s my observation after 30+ years in this business.

Leave a Reply

× seven = 28

Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books