Document your code

TODO

• Work is in progress for Gradle and Maven. See https://github.com/binkley/modern-java-practices/issues/604.
• Decide if javadoc from unit test sources is useful. Gradle does not do this without configuration; Maven does this by default.
• Decide if javadoc from integration test sources is useful. There are use cases that integration and higher-level testing provide documentation useful to users and business folks.

---

You do not just manage or work on code as an individual. It is important to share API and code details to others.

Consider code documentation as a tool for sharing with others including:

• Onboarding new contributors to your project
• Sharing code internally for review or adoption
• Sharing code to the public (open source or perhaps business partners)
• Discussing code goals and APIs with manager roles

The goal is to document your code API for review, explanation, and sharing. Typically internal "business only" code is not documented but should be self-explanatory through method and parameter naming. However, shared (public) entries to a project should be well-documented: saying too much in these kind of docs is better than saying too little, and lessens under-informed conversations.

What this exmample project provides:

• Javadoc generation from your production and test code

This project is JVM-based, so the tool of choice is Javadoc.

Note

Java 23+ may offer Markdown as an alternative for current Javadoc format. Some other JVM languages provide this at present such as Kotlin.

Gradle

The simplest approach with Gradle is to use the withJavadocJar() method inside the top-level java block in your build.gradle such as this project does. The example project generates Javadoc for only the "main" source root.

Maven

Use the maven-javadoc-plugin in your pom.xml such as this project does. The example project generates Javadoc for both "main" and "test" source roots.