Skip to content

docs: add code comment guidelines to AGENTS.md and update rule#27729

Merged
dhairyashiil merged 2 commits intomainfrom
devin/1770458356-add-comment-guidelines
Feb 7, 2026
Merged

docs: add code comment guidelines to AGENTS.md and update rule#27729
dhairyashiil merged 2 commits intomainfrom
devin/1770458356-add-comment-guidelines

Conversation

@eunjae-lee
Copy link
Copy Markdown
Contributor

@eunjae-lee eunjae-lee commented Feb 7, 2026

What does this PR do?

Adds code comment guidelines to AGENTS.md to prevent AI-generated comments that simply restate what the code does. This was prompted by team feedback:

Anyone else thinks we should stop allowing ai generated comments that simply restate what the function does?

Changes to AGENTS.md (kept lean, referencing the dedicated rule file):

  • Do section: Added bullet linking to code comment guidelines — focus on "why", not "what"
  • Don't section: Added explicit rule against restating code in comments

Changes to agents/rules/quality-code-comments.md:

  • Broadened "when to comment" to include business decisions and troubleshooting context
  • Added explicit guidance to skip comments entirely when no "why" is needed

No functional code changes — documentation only.

How should this be tested?

N/A — this is a documentation change to AI agent guidelines. Verify that the wording and examples align with the team's expectations for comment quality.

Human Review Checklist

  • Wording in the "Do" bullet accurately captures the intent (focus on "why", skip comments when no explanation is needed)
  • The link from AGENTS.md to agents/rules/quality-code-comments.md renders correctly
  • Updates to the rule file ("business decisions", "troubleshooting context", skip guidance) match the team's expectations
  • No unintended formatting issues in the markdown

Mandatory Tasks (DO NOT REMOVE)

  • I have self-reviewed the code (A decent size PR without self-review might be rejected).
  • I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. N/A
  • I confirm automated tests are in place that prove my fix is effective or that my feature works. N/A — docs only.

🔗 Devin session | Requested by @eunjae-lee

Co-Authored-By: eunjae@cal.com <hey@eunjae.dev>
@devin-ai-integration
Copy link
Copy Markdown
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR that start with 'DevinAI' or '@devin'.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

… AGENTS.md

Co-Authored-By: eunjae@cal.com <hey@eunjae.dev>
@pull-request-size pull-request-size bot added size/XS and removed size/S labels Feb 7, 2026
@devin-ai-integration devin-ai-integration bot changed the title docs: add code comment guidelines to AGENTS.md docs: add code comment guidelines to AGENTS.md and update rule Feb 7, 2026
@eunjae-lee eunjae-lee marked this pull request as ready for review February 7, 2026 10:09
@graphite-app graphite-app bot requested a review from a team February 7, 2026 10:09
@graphite-app graphite-app bot added core area: core, team members only consumer labels Feb 7, 2026
Copy link
Copy Markdown
Contributor

@cubic-dev-ai cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 2 files

@dhairyashiil dhairyashiil merged commit a57fac7 into main Feb 7, 2026
56 checks passed
@dhairyashiil dhairyashiil deleted the devin/1770458356-add-comment-guidelines branch February 7, 2026 12:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

consumer core area: core, team members only ready-for-e2e size/XS

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants