docs(generic): coach the missing concept, not the parameter count - #122
Open
devill wants to merge 1 commit into
Open
docs(generic): coach the missing concept, not the parameter count#122devill wants to merge 1 commit into
devill wants to merge 1 commit into
Conversation
The guide asks for a better object, but an agent's default answer is a bag named after the function that takes it -- a FooProps, an options object. That is organised by method rather than by abstraction, so the next function invents another bag and the concept stays unnamed. Measured on a real TypeScript codebase: five prop lists over the threshold, and three of them re-listed the members of an entity the codebase had already named somewhere else. The guide now names domain-driven design as the tool for finding the entity, says to search the codebase for the same values appearing side by side because the combinations that recur are the real one, and asks for every fitting site to be refactored rather than only the line that fired -- an abstraction used once is hidden, not introduced.
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
1 participant
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.
The problem
The guide already asks for a better object, but the agent's default answer to it is a bag named after the function that takes it — a
FooProps, an options object,{ ...everything }. That clears the report and entrenches the smell: such an object is organised by method rather than by abstraction, so the next function invents another bag and the concept stays unnamed.What I measured
On a real TypeScript codebase (a thumbnail editor, ~900 tests), five parameter lists were over the threshold. Three of the five re-listed the members of an entity the codebase had already named somewhere else — the props interface spelled out the fields instead of taking the existing type. The other two pointed at one concept that appeared independently in two files and had no name at all.
The tell was mechanical in one case: the component immediately passed four of its five props straight back out to a hook. Values that arrive together and leave together are an entity.
What the guide now says
Three additions, all terse, keeping the existing ROSE shape:
Testing
uv run pytest— the generic plugin's suite passes. 16 failures inplugins/typescriptare identical with and without this change onorigin/main(knip and comment sensors); they are not touched here.Related
There is a blind spot no guide can reach:
max-paramscounts parameters, so a props object is one parameter however many values it carries, and the guide never fires. Filed separately.🤖 Generated with Claude Code
https://claude.ai/code/session_01Xb1JpxqxY9mtqzXgQKdBYS