DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

SBOMs are essential to circumventing software supply chain attacks, and they provide visibility into various software components.

Related

  • Increase Your Code Quality in Java by Exploring the Power of Javadoc

Trending

  • Optimizing Your IDP Using Centralized Configuration Management With IBM Cloud App Configuration: A Complete Guide
  • Migrating Traditional Workloads From Classic Compute to Serverless Compute on Databricks
  • MCP Client Agent: Architecture and Implementation
  • Build AI Agents With MCP Server in C# and Run in VS Code
  1. DZone
  2. Coding
  3. Java
  4. If You Do It Do It Right

If You Do It Do It Right

By 
Peter Verhas user avatar
Peter Verhas
DZone Core CORE ·
Jun. 01, 15 · Interview
Likes (0)
Comment
Save
Tweet
Share
5.6K Views

Join the DZone community and get the full member experience.

Join For Free

This is a philosophical or ethical command. Very general. It is something like “fail fast”. The reason it came up to my mind is that I wanted to compile and release License3j using Java 8 and JavaDoc refused to compile during release build.

This package is a simple license manager, which has some established user base who require that I keep up with the new versions of BouncyCastle. It itself being a cryptography package should not be outdated and programs are encouraged to use the latest version to avoid security issues. When I executed mvn release:prepare I got many errors:

[ERROR] * <p>
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:132: error: unexpected end tag: </p>
[ERROR] * </p>
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:134: warning: no @param for args
[ERROR] public static void main(String[] args) throws Exception {
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:134: warning: no @throws for java.lang.Exception
[ERROR] public static void main(String[] args) throws Exception {
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/ExtendedLicense.java:73: warning: no @param for expiryDate
[ERROR] public void setExpiry(final Date expiryDate) {
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/License.java:196: warning: no description for @throws
[ERROR] * @throws IOException
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/License.java:246: warning: no description for @throws

New JavaDoc Wants You DIR

The errors are there because the java doc of License3j is a bit sloppy. Sorry guys, I created the code many years ago and honestly it is not only the java doc that could be improved. As a matter of fact one of the unit tests rely on network and the reachability of GitHub. (Not anymore though, I fixed that.)

The new Java version 8 is very strict regarding to JavaDoc. As you can see on the “Enhancements in Javadoc, Java SE 8” page of ORACLE:

The javadoc tool now has support for checking the content of javadoc comments for issues that could lead to various problems, such as invalid HTML or accessibility issues, in the files that are generated by javadoc. The feature is enabled by default, and can also be controlled by the new -Xdoclint option. For more details, see the output from running “javadoc -X”. This feature is also available in javac, although it is not enabled by default there.

To get the release working I had the choice to fix the JavaDoc or to use the configuration

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <additionalparam>-Xdoclint:none</additionalparam>
            </configuration>
        </execution>
    </executions>
</plugin>

in pom.xml. (Source is stackoverflow.)

But You Just Won’t DIR

You can easily imagine that you will opt for the second option when you are under time pressure. You fix the issue modifying your pom.xml or other build configuration and forget about it.

But you keep on thinking about why it is the way like that? Why is the new tool strict by default? Is it a good choice? Will it drive people to create better JavaDoc?

(Just for now I assume that the aim of the new behavior was to drive programmers to create better JavaDoc documentation and not simply to annoy us.)

I am a bit suspicious that this alone will be sufficient to improve documentation. Programmers will:

  • Switch off the lint option.
  • Delete JavaDoc from the source.
  • Write some description that Java 8 will accept but is generally meaningless.

or some of them will just write correct java doc. Some of them who were writing it well anyway and will be helped by the new strictness. How many of us? 1% or 2%? The others will just see it as a whip and try to avoid. We would need carrot instead. Hey, bunnies! Where is the carrot?

Javadoc

Published at DZone with permission of Peter Verhas, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • Increase Your Code Quality in Java by Exploring the Power of Javadoc

Partner Resources

×

Comments

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • [email protected]

Let's be friends: