alunduil / alunduil/woodland-generators

Comments in packages/core explain why, not what

オープン
#554 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
chore
主要言語
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 はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。