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.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

JPA Mini Book

Learn how to leverage the power of JPA in order to create robust and flexible Java applications. With this Mini Book, you will get introduced to JPA and smoothly transition to more advanced concepts.

JVM Troubleshooting Guide

The Java virtual machine is really the foundation of any Java EE platform. Learn how to master it with this advanced guide!

Given email address is already subscribed, thank you!
Oops. Something went wrong. Please try again later.
Please provide a valid email address.
Thank you, your sign-up request was successful! Please check your e-mail inbox.
Please complete the CAPTCHA.
Please fill in the required fields.

2 Responses 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.

  2. 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 clear documentation allows for the code to safely change without breaking usage of it.

    5. Documenting as you go is good for fast & maintainable agile development.

    There is also pointless javadoc, e.g. comments which just restates the method & parameter names. No-one should bother writing that (and hence measuring javadoc coverage is silly). But that’s an argument for *better* documentation, driven by a better understanding of your fellow developer as a user of your code.

    I’ve written more on this here: http://platypusinnovation.blogspot.co.uk/2014/08/documentation-for-educated-stranger.html

Leave a Reply


four − = 2



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy | Contact
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.
Do you want to know how to develop your skillset and become a ...
Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

Get ready to Rock!
You can download the complementary eBooks using the links below:
Close