docs(ai): single-letter variable names by KSXGitHub · Pull Request #355 · KSXGitHub/parallel-disk-usage

KSXGitHub · 2026-03-15T22:51:05Z

Summary

This PR establishes comprehensive naming conventions for variables and closure parameters in the codebase, complementing the existing generic type parameter guidelines.

Changes

CONTRIBUTING.md: Added a new "Variable and Closure Parameter Naming" section with detailed guidelines covering:
- When single-letter names are allowed (conventional names like n for count / f for formatter, comparison closures, i/j/k for indices in short closures and index-based loops, trivial single-expression closures, fold accumulators, test fixtures with identical roles)
- When single-letter names are NOT allowed (multi-line functions and closures, let bindings, function/method parameters except conventional names, non-obvious contexts)
- Concrete code examples for each case
AI instruction files (.github/copilot-instructions.md, AGENTS.md, CLAUDE.md): Updated with a concise summary of the new naming guidelines to ensure AI assistants follow the conventions

Notable Details

The guidelines strike a balance between readability and idiomatic Rust practices:

Permits single-letter names in well-established Rust idioms (e.g., |a, b| for comparisons, n for counts, f for formatters)
Restricts n to counting — indices must use index, idx, or *_index by default
Restricts i/j/k to short closures and index-based loops only
Requires descriptive names in multi-line functions and closures
Function/method parameters require descriptive names, except for conventional names (n, f, etc.)
Test fixtures allow a/b only when variables have identical, interchangeable roles — not for actual/expected
Provides clear examples to guide implementation decisions

https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Copilot

Pull request overview

Adds explicit, repo-wide guidance on when single-letter variable/closure parameter names are acceptable, extending the existing naming conventions in CONTRIBUTING and mirroring the summary into AI instruction files.

Changes:

Introduces a new “Variable and Closure Parameter Naming” section in CONTRIBUTING.md with allowed/disallowed cases and examples.
Updates AI instruction documents to include a concise summary of the new naming rules.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
CONTRIBUTING.md	Adds detailed variable/closure parameter naming rules with examples.
CLAUDE.md	Mirrors the new naming rule summary into the AI quick reference.
AGENTS.md	Mirrors the new naming rule summary into the AI quick reference.
.github/copilot-instructions.md	Mirrors the new naming rule summary into the AI quick reference.

You can also share your feedback on Copilot code review. Take the survey.

github-actions · 2026-03-15T22:58:31Z

Performance Regression Reports

commit: cdf3036

--quantity=apparent-size --max-depth=1 --min-ratio=0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`pdu`	104.9 ± 19.9	94.2	152.5	1.11 ± 0.21
`pdu-0.20.0`	94.9 ± 0.5	94.3	96.5	1.00

Logs

Benchmark 1: pdu
  Time (mean ± σ):     104.9 ms ±  19.9 ms    [User: 91.3 ms, System: 283.1 ms]
  Range (min … max):    94.2 ms … 152.5 ms    19 runs
 
  Warning: The first benchmarking run for this command was significantly slower than the rest (152.5 ms). This could be caused by (filesystem) caches that were not filled until after the first run. You are already using the '--warmup' option which helps to fill these caches before the actual benchmark. You can either try to increase the warmup count further or re-run this benchmark on a quiet system in case it was a random outlier. Alternatively, consider using the '--prepare' option to clear the caches before each timing run.
 
Benchmark 2: pdu-0.20.0
  Time (mean ± σ):      94.9 ms ±   0.5 ms    [User: 92.3 ms, System: 278.6 ms]
  Range (min … max):    94.3 ms …  96.5 ms    31 runs
 
Summary
  pdu-0.20.0 ran
    1.11 ± 0.21 times faster than pdu

JSON

{
  "results": [
    {
      "command": "pdu",
      "mean": 0.10493451423789475,
      "stddev": 0.019942310467925984,
      "median": 0.09493486208,
      "user": 0.09125513999999998,
      "system": 0.2831322505263158,
      "min": 0.09418181008000001,
      "max": 0.15246399108,
      "times": [
        0.15246399108,
        0.15059210508,
        0.14237844908000002,
        0.10985550508000001,
        0.10799729908000001,
        0.09458655908000001,
        0.09441219208000001,
        0.09582028508000001,
        0.09418181008000001,
        0.09482076808,
        0.09476568608000001,
        0.09455379808,
        0.09456714208000001,
        0.09562271408,
        0.09486891908,
        0.09493232808,
        0.09543733608,
        0.09493486208,
        0.09696402108
      ],
      "exit_codes": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    },
    {
      "command": "pdu-0.20.0",
      "mean": 0.09490035788645163,
      "stddev": 0.00046597416718243285,
      "median": 0.09480934708000001,
      "user": 0.09229662387096775,
      "system": 0.2786002658064517,
      "min": 0.09430190508000001,
      "max": 0.09649880808000001,
      "times": [
        0.09497781408000001,
        0.09483761008000001,
        0.09464434808000001,
        0.09532593708,
        0.09544141408000001,
        0.09507595708000001,
        0.09481733208000001,
        0.09649880808000001,
        0.09492111708,
        0.09455776508000001,
        0.09449502708,
        0.09483533708000001,
        0.09430190508000001,
        0.09515941408,
        0.09480679308,
        0.09483721008000001,
        0.09441095008000001,
        0.09536605208000001,
        0.09437006308000001,
        0.09452244908,
        0.09454058308,
        0.09517187708000001,
        0.09480934708000001,
        0.09467722908000001,
        0.09555427608000001,
        0.09463350708000001,
        0.09573531508000001,
        0.09476903208000001,
        0.09455278608,
        0.09474968508,
        0.09451415308000001
      ],
      "exit_codes": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
  ]
}

- Remove misleading `n` and `b` examples from trivial closures (not truly trivial; `n` implies number, `b` was fabricated) - Remove `(or `a`)` from fold accumulators — `acc` is the standard name - Clarify test fixtures require identical roles (not `actual`/`expected`) - Delete macro-generated variables bullet (misidentified reason) - Update AI instruction summaries to match https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Document that `n` is allowed for natural numbers/counts/indices and `f` for fmt::Formatter, matching established math and Rust stdlib conventions. https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Copilot

Pull request overview

This PR adds explicit conventions for variable and closure parameter naming (especially when single-letter names are acceptable) and propagates a concise summary of those rules into the repo’s AI instruction files.

Changes:

Add a “Variable and Closure Parameter Naming” section to CONTRIBUTING.md with allowed/disallowed cases and examples.
Update CLAUDE.md, AGENTS.md, and .github/copilot-instructions.md to reflect the new naming guidance for AI assistants.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
CONTRIBUTING.md	Defines the new variable/closure naming conventions with examples.
CLAUDE.md	Adds a one-line summary of the new naming conventions for AI usage.
AGENTS.md	Adds a one-line summary of the new naming conventions for AI usage.
.github/copilot-instructions.md	Adds a one-line summary of the new naming conventions for AI usage.

You can also share your feedback on Copilot code review. Take the survey.

Replace fabricated HardlinkList example (HardlinkList doesn't implement PartialEq, and add() is pub(crate) and not chainable) with a BTreeSet example that actually compiles and demonstrates interchangeable roles. https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Copilot

Pull request overview

Adds explicit, repo-wide guidance for variable and closure parameter naming, extending existing style guidance so contributors (and AI assistants) apply consistent, readable naming conventions.

Changes:

Introduces a new “Variable and Closure Parameter Naming” section in CONTRIBUTING.md with allowed/disallowed single-letter naming cases and examples.
Updates AI instruction documents to reflect the new naming rules in a concise checklist item.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
CONTRIBUTING.md	Adds detailed naming guidelines and examples for variables and closure parameters.
CLAUDE.md	Adds a one-line summary of the new naming rules for AI guidance.
AGENTS.md	Adds a one-line summary of the new naming rules for AI guidance.
.github/copilot-instructions.md	Adds a one-line summary of the new naming rules for AI guidance.

You can also share your feedback on Copilot code review. Take the survey.

- Narrow `n` to count only (not indexing); document index naming conventions (`index`, `idx`, `i`, `*_index`) - Broaden multi-line closures rule to multi-statement functions and closures - Fix contradiction: carve out exception for conventional names (`n`, `f`) in function/method parameters rule https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Copilot

Pull request overview

Adds explicit guidance on variable and closure-parameter naming to complement the existing generic type-parameter naming rules, and propagates the summary into AI instruction files to keep automated suggestions aligned with repo conventions.

Changes:

Add a new “Variable and Closure Parameter Naming” section to CONTRIBUTING.md with allowed/disallowed single-letter naming cases and examples.
Update AI instruction docs (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) to include a one-line summary of the new naming guidance.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
CONTRIBUTING.md	Introduces the new variable/closure parameter naming conventions with examples.
CLAUDE.md	Adds a concise bullet summarizing the new naming rules for AI usage.
AGENTS.md	Adds a concise bullet summarizing the new naming rules for AI usage.
.github/copilot-instructions.md	Adds a concise bullet summarizing the new naming rules for AI usage.

You can also share your feedback on Copilot code review. Take the survey.

- Add dedicated rule for `i`/`j`/`k`: allowed only in short closures and index-based loops - Wrap fn signature examples in trait/fn bodies for valid syntax - Clarify "multi-statement" → "multi-line" with concrete examples - Fix pseudocode `match { ... }` → `match { _ => todo!() }` - Update summary files (CLAUDE.md, AGENTS.md, copilot-instructions.md) https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Copilot

Pull request overview

Adds explicit guidance for variable and closure parameter naming (especially when single-letter names are acceptable) and propagates a short summary of the rule into AI instruction files so automated contributors follow the same conventions.

Changes:

Documented a detailed “Variable and Closure Parameter Naming” section in CONTRIBUTING.md.
Updated AI instruction quick references to reflect the new naming rules.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
CONTRIBUTING.md	Adds detailed, example-driven naming rules for variables/closure params.
CLAUDE.md	Adds a quick-reference summary of the new naming rules for AI usage.
AGENTS.md	Adds a quick-reference summary of the new naming rules for AI usage.
.github/copilot-instructions.md	Adds a quick-reference summary of the new naming rules for GitHub Copilot usage.

You can also share your feedback on Copilot code review. Take the survey.

- Add `type Item;` to trait Iterator example - Replace `{ ... }` with `{ todo!() }` and `{ /* ... */ }` https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Copilot

Pull request overview

Adds explicit, repo-wide guidance on when single-letter variable and closure parameter names are acceptable, and propagates a concise version of those rules into AI instruction files so automated contributions follow the same conventions as humans.

Changes:

Extend CONTRIBUTING.md with a “Variable and Closure Parameter Naming” section including allowed/disallowed cases and examples.
Update AI instruction docs to include a one-line summary of the new naming rules.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
CONTRIBUTING.md	Introduces detailed variable/closure parameter naming rules and examples.
CLAUDE.md	Adds a concise bullet summarizing the new naming conventions for AI usage.
AGENTS.md	Adds the same concise naming-convention summary for agent guidance.
.github/copilot-instructions.md	Adds the same concise naming-convention summary for Copilot guidance.

You can also share your feedback on Copilot code review. Take the survey.

- Replace `nth(n)` example with `with_capacity(n)` since `n` is for counts, not indices - Remove `i` from the conventional names note and cross-reference the dedicated i/j/k rule instead https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Copilot

Pull request overview

This PR documents and propagates a consistent convention for variable and closure-parameter naming (especially when single-letter names are acceptable) to improve readability and align human + AI contributions.

Changes:

Added a detailed “Variable and Closure Parameter Naming” section to CONTRIBUTING.md with allowed/disallowed single-letter naming cases and examples.
Updated AI instruction docs (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) to include a concise summary of the new naming guidance.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
CONTRIBUTING.md	Defines the canonical variable/closure parameter naming rules and examples.
CLAUDE.md	Mirrors the new naming rules in the AI quick-reference list.
AGENTS.md	Mirrors the new naming rules in the AI quick-reference list.
.github/copilot-instructions.md	Mirrors the new naming rules so Copilot-generated code follows the convention.

You can also share your feedback on Copilot code review. Take the survey.

docs: add variable and closure parameter naming guidelines

5a56bfd

https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

KSXGitHub changed the title ~~docs(ai): when to use single-letter names~~ docs(ai): single-letter variable names Mar 15, 2026

KSXGitHub requested a review from Copilot March 15, 2026 22:51

Copilot started reviewing on behalf of KSXGitHub March 15, 2026 22:51 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

KSXGitHub commented Mar 15, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

KSXGitHub requested a review from Copilot March 15, 2026 23:14

Copilot started reviewing on behalf of KSXGitHub March 15, 2026 23:14 View session

docs: add conventional single-letter names (n, f) to naming guidelines

c8d001a

Document that `n` is allowed for natural numbers/counts/indices and `f` for fmt::Formatter, matching established math and Rust stdlib conventions. https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

Copilot AI reviewed Mar 15, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md

KSXGitHub requested a review from Copilot March 15, 2026 23:20

Copilot started reviewing on behalf of KSXGitHub March 15, 2026 23:20 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

KSXGitHub requested a review from Copilot March 15, 2026 23:26

Copilot started reviewing on behalf of KSXGitHub March 15, 2026 23:27 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

KSXGitHub requested a review from Copilot March 15, 2026 23:46

Copilot started reviewing on behalf of KSXGitHub March 15, 2026 23:46 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

docs: fix invalid Rust syntax in code examples

f7c5603

- Add `type Item;` to trait Iterator example - Replace `{ ... }` with `{ todo!() }` and `{ /* ... */ }` https://claude.ai/code/session_01X9XkBJTA4nYi6gVT71iA1g

KSXGitHub requested a review from Copilot March 15, 2026 23:52

Copilot started reviewing on behalf of KSXGitHub March 15, 2026 23:52 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

KSXGitHub requested a review from Copilot March 15, 2026 23:58

Copilot started reviewing on behalf of KSXGitHub March 15, 2026 23:59 View session

Copilot AI reviewed Mar 16, 2026

View reviewed changes

KSXGitHub marked this pull request as ready for review March 16, 2026 00:02

KSXGitHub merged commit 40a6709 into master Mar 16, 2026
16 of 17 checks passed

KSXGitHub deleted the claude/standardize-ai-instructions-sVkG0 branch March 16, 2026 00:03

Uh oh!

Conversation

KSXGitHub commented Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Notable Details

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

github-actions Bot commented Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance Regression Reports

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

KSXGitHub commented Mar 15, 2026 •

edited

Loading

github-actions Bot commented Mar 15, 2026 •

edited

Loading