Issue numbers and codewords in code comments: 380 of them, against a rule that says none
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 14
- Forks
- 2
- Avg merge
- 12h 42m
- Merged PRs (30d)
- 61
Description
agents/Coding.md says:
Dont write issue numbers, or codewords (like S1, C1.2 etc) in the code itself.
The tree disagrees, at scale:
| tree | comment references to an issue |
|---|---|
src/ |
226 |
tests/ |
122 |
scripts/ |
27 |
runtime/ |
5 |
plus 84 S1/C1.2-style codewords in src/ comments.
They are dense enough that matching the surrounding style is what an agent reading the code will do, which is how they keep accumulating — the local evidence is stronger than the rule. That is the thing to fix: either the comments or the rule, not one instance at a time.
What is worth keeping and what is not
Most of these do real work for a reader: (Vx#399) next to a decision records why the code is shaped that way, and the issue holds the argument that the comment only gestures at. Deleting the reference does not remove the dependency, it hides it.
The ones that read badly are different: a reference used instead of an explanation (// handled differently now (#242)), or one attached to code whose issue closed years of refactors ago.
So a sweep should not be mechanical. A reasonable split:
- Where the comment explains the reasoning and the issue is the citation — rewrite so the sentence stands alone, and drop the number.
- Where the number is the explanation — the comment needs writing, not editing.
- Codewords (
S1,C1.2,M2b-2,§5.4) — these name sections of plan documents that have since moved or merged, and are the least recoverable of the three. Highest value to remove.
Until then
New code does not add them. Going forward is the cheap half; this issue is the accumulated half.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with agents/Coding.md, then inventory comment references in src/, tests/, scripts/, and runtime/. Classify each reference as reasoning that should stand alone, an unexplained issue citation, or a codeword such as S1 or C1.2. Done means the accumulated comments and codewords have been reviewed and rewritten or removed without adding new references.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100