java-code-standards

Java Code Style and Standards

Context

• When writing Java code
• When reviewing Java code
• When modifying existing Java code
• When implementing new features
• When refactoring existing code
• Applies to projects using Java 21 or later

Requirements

Class Documentation

Provide Javadoc for classes that form the public API surface or are externally consumed, and for classes whose intent is non‑obvious. Internal or trivial classes do not require Javadoc.

IMPORTANT: Do NOT include @author, @version, or @since tags in Javadoc comments. These tags are not needed and should not be added by code generation tools or agents.

/**
 * Brief one-line description of the class.
 * <p>
 * More detailed description of the class functionality,
 * including its purpose, key features, and usage examples.
 * </p>
 */

Method Documentation

Document methods that are part of the public API surface (externally consumed) or that have non‑obvious behavior, side-effects, or constraints. For trivial/internal methods, method-level Javadoc is optional.

/**
 * Brief description of what the method does.
 * <p>
 * More detailed description if necessary, including any
 * important implementation details or usage notes.
 * </p>
 *
 * @param paramName Description of the parameter
 * @return Description of the return value
 * @throws ExceptionType Description of when/why this exception is thrown
 * @see RelatedClass#relatedMethod()
 */

Field Documentation

Document all class-level fields that are part of the public API:

/** Maximum number of retry attempts for the operation */
private static final int MAX_RETRIES = 3;

/** Current status of the operation */
private OperationStatus status;

Code Organization

1. Class Structure (in order):
   • Package declaration
   • Imports (organized and grouped)
   • Class documentation
   • Class declaration
   • Static fields
   • Instance fields
   • Constructors
   • Public methods
   • Protected methods
   • Private methods
   • Inner classes