Clarify Java Comments

Clarify Java Comments

Produce concise documentation that preserves the contract, useful conclusions, and important hidden behavior without narrating every inference or obvious implementation step. Treat existing comments and PR descriptions as claims to verify against the current source.

Scope the work

• Review or edit only the Javadocs and explanatory code comments changed by the diff or explicitly named by the user.
• Read enough surrounding implementation, tests, and callers to verify every retained claim. Report an inaccurate claim instead of preserving it in smoother prose.
• Before shortening a comment, inventory its distinct technical claims and invariants. Classify each as supported and important, obvious or redundant, or unsupported. Preserve every supported non-obvious item in the rewrite.
• Stay documentation-focused. Do not expand into a general correctness or performance review unless a behavioral issue makes the proposed Javadoc false.

Route the workflow

Read all references that apply to the request:

• Javadoc tags for whole-comment rewrites or explicit tag repair.
• Local edits before changing documentation in the checkout. A path selects a target but does not authorize an edit.
• GitHub reviews before any GitHub review workflow. Posting, replying, editing, and submitting each require the separate authorizations defined there.

Decide what deserves explanation

Use this deletion test before shortening or removing explanatory detail: would its absence make a competent maintainer likely to miss a material constraint or have to reconstruct it through specialist knowledge or non-local investigation?

• Keep a verified explanation when it affects the API contract, correctness, safe modification, compatibility, or performance and is not cheaply recoverable from the signature and nearby straight-line code using ordinary Java knowledge.
• Treat behavior as non-obvious when it is implicit in the platform or runtime, such as JVM, Java Memory Model, or JIT behavior; when its cause or effect lies elsewhere, such as in a caller, lifecycle, generated bytecode, or downstream consumer; or when the local code requires specialist reasoning about synchronization, memory visibility, interleavings, type profiling, allocation, or escape analysis.
• Preserve the shortest causal chain that explains the constraint: the condition or mechanism, the resulting effect or invariant, and why it matters to callers or future changes. Omit intermediate proof steps once that chain is understandable.
• Omit prose that only restates names, types, syntax, or visible control flow; repeats the same contract or conclusion; catalogs irrelevant alternatives or history; or adds technical detail without a reader-relevant consequence.
• Do not equate proximity with obviousness. Nearby code can require explanation, and distant or technical behavior should be retained only when it materially matters.

Rewrite for readers

• Lead with the API contract or purpose. Apply the decision rule above to any explanatory detail beyond that contract.
• Express each retained explanation as a compact causal chain rather than narrating every inference.
• Do not remove JVM internals merely because they are arcane. When relevant, retain matters such as Java Memory Model publication and happens-before guarantees, safe traversal through retained links, HotSpot escape analysis or devirtualization, composite-key allocation, identity fast paths and boxing, atomic updater and reservation accounting, or type erasure in runtime containers such as AtomicReferenceArray. These are examples of details to preserve, not a checklist of content to invent.
• Define specialist terms on first use. Prefer one compact explanation over a historical detour or a list of what the code does not do.
• State a supported conclusion once. Retain only the reasoning needed to satisfy the decision rule above and make the conclusion safe to act on.
• Use a one-line Javadoc for an obvious delegate or predicate. Use paragraphs only when they carry distinct information.
• For benchmark documentation, separate inputs and setup from measured results and conclusions. Keep existing JMH result tables and numbers when present unless the user asks to remove them or evidence shows that they are stale or invalid. Retain the environment details needed to interpret the numbers, and remove speculation that was not measured. If results are unreliable, flag the problem instead of silently replacing the evidence with prose.
• Prefer <pre>{@code ...}</pre> for a useful copy-ready example. Do not add an example when the signature already makes usage clear.
• When a claim depends on JVM, library, or tool behavior outside the repository, verify it with primary sources such as OpenJDK source or the maintained project's official documentation. Do not rely on commercial aggregator sites.
• Use plain international English. Remove stacked parentheticals, repeated claims, conversational asides, promotional adjectives, and long "not to be confused with" passages.