alunduil / alunduil/woodland-generators
Comments in packages/core explain why, not what
- 主要言語
- TypeScript
- スター
- 0
- フォーク
- 0
- 平均マージ
- 5時間 35分
- マージ済み PR(30日)
- 105
説明
## Summary
Several comments in `packages/core/src/` narrate the line beneath them, and one
module docstring sells the module rather than describing it. None would tell a
stranger anything the code doesn't.
## Motivation
`generators/core/choices.ts` announces each call by restating its name:
```ts
// Validate choices are non-empty
validateChoicesNonEmpty(category, choices, logger);
// Validate user selection if provided
if (selection) {
```
The same pair repeats at `:88` and `:91`, and the function itself carries
`/** Validate that choices array is non-empty */` above
`validateChoicesNonEmpty`. `demeanor.ts:36` and `details.ts:37` do the same for
their generate calls, as does `name.ts:65` above a `new Rng(...)`.
`generators/core/index.ts` spends eleven lines on two export statements:
```
* This module provides a comprehensive set of reusable functions for:
* …
* All functions follow consistent patterns with proper error handling,
* logging, and type safety. User selection validation is integrated
* directly into generation functions for a simplified, robust API.
```
"Comprehensive", "proper", "robust", "simplified" are packaging;
`techwriting.md` calls for the plainest available words. "Type safety" is
TypeScript's, not the module's.
Two smaller items: `character/types.ts:20` carries
`// Add more character properties as needed`, an instruction to a future editor
rather than a fact about the type; and `species.ts:19-29` enumerates the eight
ecological categories that the array below already labels inline at `:34` and
after.
Worth keeping, for contrast — `generators/core/rng.ts` explains why FNV-1a is
enough (deterministic and low-collision, because the engine does the mixing),
why the wrapper exists (the PRNG stays swappable), and what
`selectUniqueRandomElements` returns when the pool is short. None of that is
recoverable from the code. The rest of `species.ts`'s header is the same shape:
the Root RPG constraints behind the curated list are real domain knowledge.
## Scope
- Delete the restating comments in `choices.ts`, `demeanor.ts`, `details.ts`,
and `name.ts`.
- Rewrite `generators/core/index.ts`'s docstring to say what the module holds,
or delete it.
- Drop `character/types.ts:20` and `species.ts`'s category enumeration.
- Leave `rng.ts` and `species.ts`'s constraint list alone.
## Acceptance criteria
- [ ] No comment in `packages/core/src/` restates the statement below it
- [ ] `generators/core/index.ts` makes no claim about quality or type safety
- [ ] `rng.ts`'s explanatory comments survive intact
- [ ] `pre-commit run --all-files` passes
## Additional context
Surfaced auditing comments on #548, which removed the stale
"using functional approach" phrasing from the same files — that wording
distinguished these generators from the class-based ones deleted in that PR.
No sensor catches any of this: Vale is scoped to `.md`/`.rst`/`.txt` and its
code-file section ignores comment bodies. That's #553.
コントリビューションガイド
評価
この issue はまだ評価されていません。