Document your code
- Work is in progress for Gradle and Maven. See https://github.com/binkley/modern-java-practices/issues/604.
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.
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.
See the code repo for working examples.
This work is dedicated/deeded to the public following laws in jurisdictions
for such purpose.
The principal authors are: