Add a skill to clarify Java comments - #12362
Conversation
bric3
added
type: documentation
tag: no release notes
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
This comment has been minimized.
This comment has been minimized.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d87ee17e25
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![datadog-datadog-prod-us1[bot]](https://avatars.githubusercontent.com/u/365230?s=60&v=4){kind=small}
There was a problem hiding this comment.
The skill cannot run its required Gradle checks because it names a command that this repository does not provide.
🤖 Datadog Autotest · Commit d87ee17 · What is Autotest? · @DataDog review to ask questions · Any feedback? Reach out in #autotest
🟢 Java Benchmark SLOs — All performance SLOs passed
PR vs. master results
Commit: Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion. |
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f6d8a8d65e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
One question on the new Given this skill can edit local files, post GitHub review comments, and run |
sarahchen6
left a comment
sarahchen6
left a comment
There was a problem hiding this comment.
I support this skill given more and more AI contributions!
In general, I think the skill is a bit verbose though. I started leaving some comment suggestions, but we should rework to keep instructions minimal so not to overwhelm the context of the AI using this, similar to existing skills like for techdebt: https://github.com/DataDog/dd-trace-java/blob/master/.agents/skills/techdebt/SKILL.md.
WDYT about centering the skill around existing best practices like https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/? I think defining these 9 rules plus a bit of context is sufficient and straightforward.
| Clarify or review Java Javadocs, Javadoc tags, and explanatory code comments for | ||
| legibility, accuracy, and source alignment. Use when asked to simplify verbose or | ||
| generated comments, edit documentation in a local file, class, or member, repair | ||
| Javadoc markup, propose copy-ready replacements, or add GitHub suggestions to an | ||
| existing pending PR review. Documentation-focused: never change executable code | ||
| or turn the task into a general code review. Do not submit a review unless | ||
| explicitly requested. |
There was a problem hiding this comment.
| Clarify or review Java Javadocs, Javadoc tags, and explanatory code comments for | |
| legibility, accuracy, and source alignment. Use when asked to simplify verbose or | |
| generated comments, edit documentation in a local file, class, or member, repair | |
| Javadoc markup, propose copy-ready replacements, or add GitHub suggestions to an | |
| existing pending PR review. Documentation-focused: never change executable code | |
| or turn the task into a general code review. Do not submit a review unless | |
| explicitly requested. | |
| Clarify or review Java Javadocs, Javadoc tags, code comments, and documentation for concision, | |
| legibility, accuracy, and source alignment. Use when asked to improve or simplify verbose | |
| comments, documentation, Javadoc markup, etc. Documentation-focused: never change | |
| executable code or turn the task into a general code review. Do not submit a review unless | |
| explicitly requested. |
| - For a PR, pin the live head and base before drafting suggestions. Refresh them | ||
| before posting because comment ranges and conclusions are revision-specific. | ||
| - Preserve unrelated tracked and untracked work. Keep any authorized local edit | ||
| limited to the comments in scope, and do not switch branches in a dirty checkout | ||
| merely to inspect a PR. |
There was a problem hiding this comment.
I don't think these two bullets are necessary to specify, as I find it a part of general Codex, etc. workflow
| - Put the main point first. Use a concrete subject and an active verb where practical. | ||
| - Keep one idea per sentence and one purpose per paragraph. Split nested clauses and | ||
| long parenthetical chains. | ||
| - Name the relevant method, state, or JVM mechanism instead of relying on an unclear | ||
| pronoun or distant antecedent. | ||
| - Keep the connective sentence that makes a causal relationship understandable. | ||
| Concision must not make the text compressed, cryptic, or abrupt. | ||
| - Use terminology that matches the code and domain. Replace vague generated labels | ||
| with names a maintainer would naturally use. | ||
| - Read the replacement once in its surrounding context. If understanding a sentence | ||
| requires backtracking to find its subject, condition, or conclusion, rewrite it. |
There was a problem hiding this comment.
| - Put the main point first. Use a concrete subject and an active verb where practical. | |
| - Keep one idea per sentence and one purpose per paragraph. Split nested clauses and | |
| long parenthetical chains. | |
| - Name the relevant method, state, or JVM mechanism instead of relying on an unclear | |
| pronoun or distant antecedent. | |
| - Keep the connective sentence that makes a causal relationship understandable. | |
| Concision must not make the text compressed, cryptic, or abrupt. | |
| - Use terminology that matches the code and domain. Replace vague generated labels | |
| with names a maintainer would naturally use. | |
| - Read the replacement once in its surrounding context. If understanding a sentence | |
| requires backtracking to find its subject, condition, or conclusion, rewrite it. | |
| - Put the main point first. | |
| - Keep one idea per sentence and one purpose per paragraph. | |
| - Name the relevant method, state, or JVM mechanism instead of relying on an unclear | |
| pronoun or distant antecedent. | |
| - Use terminology that matches the code and domain. Replace vague generated labels | |
| with names a maintainer would naturally use. |
| tag. Apply this bonus pass only to a whole-comment rewrite or an explicit tag-repair | ||
| request. For a sentence-, typo-, or wording-limited request, leave unrelated tags | ||
| unchanged and report any separate defect. |
There was a problem hiding this comment.
| tag. Apply this bonus pass only to a whole-comment rewrite or an explicit tag-repair | |
| request. For a sentence-, typo-, or wording-limited request, leave unrelated tags | |
| unchanged and report any separate defect. | |
| tag. |
| is already clear. | ||
| - Never modify suppression directives, generated markers, license text, or tooling | ||
| instructions in this skill. Preserve TODO/FIXME ownership and status; rewrite only | ||
| their explanatory prose when the user explicitly names it. |
There was a problem hiding this comment.
| their explanatory prose when the user explicitly names it. | |
| - Preserve the comment's form and scope unless the user requests an API documentation change. | |
| - Keep comments that record an invariant, a non-obvious reason, a compatibility | |
| constraint, or a deliberate tradeoff. Remove line-by-line narration of code that | |
| is already clear. | |
| - Never modify suppression directives, generated markers, license text, or tooling | |
| instructions in this skill. | |
| Preserve TODO/FIXME ownership and status. |
| instructions in this skill. Preserve TODO/FIXME ownership and status; rewrite only | ||
| their explanatory prose when the user explicitly names it. | ||
|
|
||
| ## Local edit mode |
There was a problem hiding this comment.
I think this section is a bit redundant.... Most of these points are inherent and Codex already does a good enough job at this. We should try to minimize unnecessary rules to reduce context needed by this skill.
3 participants
What Does This Do
Adds the
clarify-java-commentsCodex skill for reviewing or rewriting JavaJavadocs and explanatory comments.
The skill provides source-grounded guidance for:
Tip
At this time, this skill works WAY better with codex.
Motivation
Claude-generated Javadoc and comments often narrate every inference instead of providing useful documentation for human readers. This makes contracts, invariants, and important JVM behavior harder to find and understand.
The skill defines a reusable boundary: retain verified explanations that materially affect the contract, correctness, safe modification, compatibility, or performance
when they are not readily recoverable from nearby code. It should express that reasoning as the shortest useful causal chain and remove the rest.
Additional Notes
authorization boundaries.
Contributor Checklist
type:and (comp:orinst:) labels in addition to any other useful labelsclose,fix, or any linking keywords when referencing an issueUse
solvesinstead, and assign the PR milestone to the issue