Docs: Rewrite AGENTS.md comment and Javadoc guidance - #18167
Merged
Merged
Conversation
Guidance lived in three Code Style bullets. The failure mode it targets -- Javadoc that documents the implementation instead of the contract -- keeps recurring in review, so this gives it a section and a check that can be applied while writing: if a comment would need editing during a behavior-preserving refactor, it describes internals. One worked example contrasts the two. Not obvious from the diff: the rules are scoped to newly written code and say to leave existing comments alone, and api/ keeps brief @PARAM and @return tags, matching the module's convention. --- **AI Disclosure** - Model: Claude Opus 5 - Platform/Tool: GitHub Copilot CLI - Human Oversight: Iteratated multiple times and Fully reviewed - Prompt Summary: Make Javadoc short and only added when it adds value, comments only when not deducible from the code, and Javadoc describe the goal of a method rather than its internals. Generated-by: GitHub Copilot CLI (Claude Opus 5) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
nastra
approved these changes
Sep 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Guidance lived in three Code Style bullets. The failure mode it targets: Javadoc that documents the implementation instead of the contract. This keeps recurring in review, so this PR gives it a section and a check that can be applied while writing: if a comment would need editing during a behavior-preserving refactor, it describes internals. One worked example contrasts the two. Not obvious from the diff: the rules are scoped to newly written code and say to leave existing comments alone, and api/ keeps brief @PARAM and @return tags, matching the module's convention.
AI Disclosure
Generated-by: GitHub Copilot CLI (Claude Opus 5)