Java Documentation (Javadoc) Best Practices

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.

Files1

1 files · 1.0 KB

Select a file to preview

Overall Score

65/100

Grade

C

Adequate

Safety

92

Quality

58

Clarity

72

Completeness

52

Summary

This skill provides structured guidance on Javadoc best practices for documenting Java types, methods, and members. It outlines conventions for comment structure, tag usage (@param, @return, @throws, @see, etc.), and documentation patterns for public, protected, and private members.

Detected Capabilities

code analysisdocumentation guidancestatic pattern recognition

Trigger Keywords

Phrases that MCP clients use to match this skill to user intent.

write javadoc commentsdocument java methodsjavadoc best practicesadd api documentationjava code documentation

Use Cases

Documenting public API methods with Javadoc comments
Adding parameter and return value documentation to existing code
Standardizing documentation for private and package-private members
Creating consistent documentation across a Java project
Learning Javadoc tag syntax and best practices

Quality Notes

Skill provides clear, comprehensive Javadoc guidelines with tag explanations
Content is well-organized as a reference list rather than step-by-step instructions
No concrete examples provided (code samples would improve clarity)
Missing guidance on when to apply different documentation levels (public vs. private)
Lacks instructions on how to apply these rules to existing codebases
No error handling or edge case guidance for complex documentation scenarios
No scope boundaries defined — unclear whether this covers inheritance patterns or generic type documentation depth

Model: claude-haiku-4-5-20251001Analyzed: Jun 26, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

java-docs