Skip to content

Rank function-name verbs by what the function returns #1277

Description

@williamthorsen

Problem

## Verb-led function names in packages/agents/content/skills/_data/naming-conventions.md requires a transitive verb but gives no basis for choosing one. Its common-verbs list -- build, create, compute, fetch, find, get, load, parse, resolve, validate -- is flat, so get reads as a peer of the rest rather than as a fallback. A codebase following the rule as written can still name an array-returning function, a Set-returning one, a single-or-undefined one, a formatted-string one, and a scalar retrieval all get*, which is what williamthorsen/toolbelt#100 found across six packages.

Proposed solution

Add a return-kind rule to ## Verb-led function names, so the verb is chosen by what the function returns and what it does rather than picked from an unranked list.

Returns Name
one or none find*
an array list*
any other container the most specific accurate verb, with the container named in the tail (*Set)
a scalar or a record the most specific accurate verb

get* is the fallback for when no more specific verb is accurate, not the default.

The container-in-the-tail clause is the existing ## Kind in the tail rule applied to a return value, so the two sections agree rather than compete.

Placement is naming-conventions.md, not a new rulebook: williamthorsen-code-layout-preferences already delegates identifier naming there, and get's mis-ranking is in that file's own list. Should the convention be judged personal rather than shared, it belongs in that rulebook instead, with the shared file keeping only the demotion of get.

Acceptance criteria

Must have

  • The return-kind rule is stated where identifier naming is specified, with ✅/❌ examples in the form the neighboring sections use.
  • get is described as the fallback rather than listed as a peer verb.
  • The rule and ## Kind in the tail are consistent about naming a returned container.

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureAdded or improved external functionalityscope:agents

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions