FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Constrain comment length and scope in AGENTS.md by stephenliang · Pull Request #74797 · code-dot-org/code-dot-org · GitHub

Constrain comment length and scope in AGENTS.md - #74797

Open
stephenliang wants to merge 1 commit into
stagingfrom
stephen/agents-comment-style
Open

Constrain comment length and scope in AGENTS.md#74797
stephenliang wants to merge 1 commit into
stagingfrom
stephen/agents-comment-style

Conversation

stephenliang commented Aug 21, 2026
edited
Loading

Copy link
Copy Markdown
Member

This PR adds a comment style block to AGENTS.md to attempt to reduce comment verbosity and density.

Before and after

Same task, same file, identical function body. Only the comment differs. The task plants one fact the code cannot show: this sort has to match the collation a Rails helper uses, or pagination between the two views disagrees.

Without it:

export function activeStudents(students: Student[]): Student[] {
  return students.filter(student => student.signedInAt !== null);
}

/**
 * Sort students by name using a case-insensitive comparison.
 * Uses `localeCompare` with `sensitivity: 'base'` rather than `<` because the
 * same roster is also rendered by a Rails helper that orders with MySQL's
 * utf8mb4_general_ci collation; the two orderings must agree or pagination
 * drifts between the two views.
 */
export function sortByName(students: Student[]): Student[] {
  return [...students].sort((a, b) =>
    a.name.localeCompare(b.name, undefined, {sensitivity: 'base'}),
  );
}

With it:

export function activeStudents(students: Student[]): Student[] {
  return students.filter(student => student.signedInAt !== null);
}

export function sortByName(students: Student[]): Student[] {
  // Matches MySQL's utf8mb4_general_ci collation used by the Rails-rendered
  // roster, so pagination order agrees between the two views.
  return [...students].sort((a, b) =>
    a.name.localeCompare(b.name, undefined, {sensitivity: 'base'}),
  );
}

Two more exports from the same file, again byte-identical bodies.

Without it:

/**
 * Students who have signed in at least once.
 */
export function activeStudents(students: Student[]): Student[] {
  return students.filter(student => student.signedInAt !== null);
}

/**
 * Total students and how many of them are active (signed in at least once).
 */
export function rosterSummary(students: Student[]): {
  total: number;
  active: number;
} {

With it:

export function activeStudents(students: Student[]): Student[] {
  return students.filter(student => student.signedInAt !== null);
}

export function rosterSummary(students: Student[]): {
  total: number;
  active: number;
} {

Across three attempts each, the file carried 16, 9, and 12 comment lines without the section, and 2, 2, and 2 with it.

Context cost

59 new tokens but it should be a net decrease as time & tokens spent on reducing comment verbosity go away.

Links

  • Jira:

Testing story

I built a test harness on Opus which is instructed to spawn Sonnet subagents which reads context and writes a file. Variations of the AGENTS.md file were submitted to subagents, and a score was assigned to commenty verbosity and denisty along with a blinded judge. I inspected the results for quality, verbosity, and density.

Five wordings, three runs per module, twenty-seven simulations.

sectionRoster.ts consentStore.ts
comment lines with no rule, as today between 9 and 16 not run
comment lines with this section 2 in every run between 4 and 12
the Rails collation fact kept in every run n/a
opening paragraph correctly absent in every run present in every run

Wordings shorter than this one lost the paragraph on consentStore.ts. Wordings longer than it put a docblock on every export of sectionRoster.ts.

stephenliang marked this pull request as ready for review August 21, 2026 19:56
The rule meant to prevent over-commenting lived only in individual
contributors' homedir config, so it bound nobody else, and it carried no
length constraint. Add a Comments section to the repo file instead.

Wording is the shortest of five measured variants that passes both a
must-stay-quiet fixture and a needs-orientation fixture.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
stephenliang force-pushed the stephen/agents-comment-style branch from 9c6e044 to 5aa335e Compare August 21, 2026 20:23
Comment thread AGENTS.md

## Comments

Never narrate what the code does. Comment only a fact a reader cannot recover from the code. One line each; never a paragraph.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

One line each; never a paragraph.

Seems drastic, since I often write paragraphs to explain why the code does something. but, seems better to include than not, to reduce the current level of over-explaining.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants


Back | FazBrowse Home | New Git URL