Java Documentation (Javadoc) Best Practices

Optimized for current Java LTS releases, JavaDoc doclint, Maven or Gradle builds, and module-aware API documentation.

• Public and protected members should be documented with Javadoc comments.

• It is encouraged to document package-private and private members as well, especially if they are complex or not self-explanatory.

• The first sentence of the Javadoc comment is the summary description. It should be a concise overview of what the method does and end with a period.

• Use @param for method parameters. The description starts with a lowercase letter and does not end with a period.

• Use @return for method return values.

• Use @throws or @exception to document exceptions thrown by methods.

• Use @see for references to other types or members.

• Use {@inheritDoc} to inherit documentation from base classes or interfaces.

  • Unless there is major behavior change, in which case you should document the differences.

• Use @param <T> for type parameters in generic types or methods.

• Use {@code} for inline code snippets.

• Use <pre>{@code ... }</pre> for code blocks.

• Use @since to indicate when the feature was introduced (e.g., version number).

• Use @version to specify the version of the member.

• Use @author to specify the author of the code.

• Use @deprecated to mark a member as deprecated and provide an alternative.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Documentation Stack Reference

Inherit the shared stack from documentation-patterns: source-of-truth discovery, audience framing, structure selection, verification, and freshness checks. Keep this skill focused on Java API documentation specifics instead of restating the full stack.

Anti-Patterns

• Repeating the method signature in prose: JavaDoc is most useful when it adds intent, constraints, and failure semantics.
• Leaving exceptions or side effects undocumented: Callers cannot use the API safely if the contract is only visible in code.
• Publishing examples that no longer compile: Broken snippets damage trust faster than missing snippets.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Java Docs output identifies audience, purpose, source of truth, and freshness requirements.
2. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
3. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
4. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
5. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.

Before and After Example

// Before
/** Gets a user. */
User getUser(String id);

// After
/**
 * Loads a user by identifier.
 *
 * @param id stable user identifier from the identity provider
 * @return persisted user record when found
 * @throws UserNotFoundException when the identifier does not resolve
 */
User getUser(String id);

Documents inputs, outputs, and failure conditions so the API contract is clear to callers and reviewers.

Common Pitfalls

• Explaining what the method name already says: JavaDoc should capture intent, constraints, and side effects, not repeat the signature.
• Leaving exceptions undocumented: Callers cannot use the API safely if failure modes are only visible in implementation.
• Letting examples lag behind the code: Outdated snippets make the docs look trustworthy while teaching the wrong contract.

<!-- MCP:START --> <!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

• GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the workflow in project instructions when folder discovery is unavailable.
• Claude Code: keep the folder in a local skills directory or a compatible plugin source.
• Codex: install or sync the folder into $CODEX_HOME/skills/java-docs and restart Codex after major changes.

<!-- PORTABILITY:END -->

MCP Availability And Fallback

Preferred MCP Server: None required

• Fallback prompt: "Use the Java Documentation (Javadoc) Best Practices skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
• Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.

<!-- MCP:END -->

Related Skills

• java-junit: Use it when the workflow also needs JUnit 5 testing practices in Java.
• documentation-authoring: Use it when the workflow also needs drafting structured technical or product documents.
• documentation-quality: Use it when the workflow also needs documentation review standards and quality gates.
• code-quality: Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.