[MINOR][DOC] Suggest grouping code into sections when adding class members in AGENTS.md - #57803
[MINOR][DOC] Suggest grouping code into sections when adding class members in AGENTS.md#57803szehon-ho wants to merge 2 commits into
Conversation
Generated-by: Cursor (Opus 5)
|
@cloud-fan @HyukjinKwon do you have any thought on it? i sometimes find annoying the ai generate a private method and put it on top |
|
I don't have a strong opinion, but it makes sense to me and can be nicer to have this, so +1 |
|
|
||
| Spark Connect protocol is defined in proto files under `sql/connect/common/src/main/protobuf/`. Read the README there before modifying proto definitions. | ||
|
|
||
| When adding a member to an existing class, prefer a position that does not split up what is already there. A good default for a new private helper is after the public methods that use it, or alongside the file's existing helpers; in a test suite, after the `test(...)` blocks rather than between them. The common failure mode is placing a helper immediately above the first method that uses it, which interrupts a top-to-bottom read of the class's public surface or of the suite's list of cases. Conventions vary between files, so follow the local one rather than reorganizing. |
There was a problem hiding this comment.
shall we turn it into a more general code placement principle? e.g. we should group the code into sections
There was a problem hiding this comment.
Good idea -- updated to a more general section-grouping principle: keep related kinds of code in sections and append a new member to the matching section, rather than a rule specific to private helpers. Kept a short note on the common failure mode of inserting a member next to its first use and splitting the surrounding section.
Address review feedback: state the general principle of grouping members into sections and appending to the matching one, instead of a rule specific to private helpers.
szehon-ho
changed the title
|
|
||
| Spark Connect protocol is defined in proto files under `sql/connect/common/src/main/protobuf/`. Read the README there before modifying proto definitions. | ||
|
|
||
| When adding members to an existing class or object, keep related kinds of code in sections rather than inserting into the middle of another section. A common layout is fields and constructors first, then the public/override API, then private helpers; in a test suite, tests together and helpers after them. Prefer appending to the matching section, or following the file's existing sectioning -- the common failure mode is inserting a new member next to its first use and splitting the surrounding section. Do not reorganize existing members unless the change requires it. |
There was a problem hiding this comment.
can you ask AI to do more research? e.g. tests together and helpers after them looks inefficient. People usually add new test cases in the end, so putting helpers at the end is easier to cause conflicts.
4 participants
What changes were proposed in this pull request?
Adds one paragraph to the
## Development Notessection ofAGENTS.mdon where to place new members when editing an existing class or object: keep related kinds of code in sections and append a new member to the matching section, rather than inserting it into the middle of another section. It sketches a common layout (fields and constructors, then the public/override API, then private helpers; in a test suite, tests together with helpers after them) and names the failure mode it is meant to prevent -- inserting a new member next to its first use and splitting the surrounding section.It is phrased as a suggestion with a default, not a rule. Files in the repo vary in how they order members, so the note defers to the file's existing sectioning and explicitly does not ask anyone to reorganize existing code.
Why are the changes needed?
Agents writing code top-down tend to define a member immediately above its first use, which lands it in the middle of a class's public surface or a suite's list of test cases and interrupts a top-to-bottom read. I hit exactly this while writing a test suite and had to move the code in review.
This fits the existing pattern of the surrounding notes, which call out specific, recurring failure modes (non-ASCII characters in comments, overrunning the 100-character line limit) rather than restating general style guidance. Unlike those two, this one has no linter behind it, so the note is the only signal available.
Does this PR introduce any user-facing change?
No. Documentation for contributors and agent tooling only.
How was this patch tested?
No tests; documentation only. Verified the added text is pure ASCII, per the rule in the paragraph immediately below it:
Was this patch authored or co-authored using generative AI tooling?
Generated-by: Cursor (Opus 5)