docs: cut the comments that were not earning their place
I wrote 731 comment lines on this branch against 4,530 lines of code — 14%, where the rest of the repo runs at 1.8%. CLAUDE.md asks for code that reads like its surroundings, and this did not. Removed by genre rather than by taste: - restating the code, e.g. "JS getUTCDay() numbering: Sunday = 0" above the map that literally shows it, and a docblock on startOfWeek explaining that it returns the start of the week; - narrating history — "this used to rebuild the whole map", "left the bar recording forever" — which the commit message and git blame already carry; - saying the same thing in several places: the "cannot record is not a denied microphone" reason appeared three times in one file, and the "aborting stops a per-minute metered call" reason across three files. Each now lives once, where the behaviour it explains lives; - defending decisions nobody would question, like why toLatinDigits is its own module; - over-explaining defensive branches, three separate comments to distinguish null from missing-kind from unrecognised-kind. What stays is what the code cannot say: the patient-right convention in toFdi, whose failure mode is a valid code for the wrong tooth; the "this"-vs-"next" week anchoring; StrictMode re-arming mountedRef; Safari accepting no mimeType hint; and the invariants whose violation already cost a bug — the body parser's middleware ordering and the dispatch panel's auto-fill rules. Comments only. The diff contains no non-comment line. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -14,10 +14,9 @@ export type Arch = 'upper' | 'lower';
|
||||
export type PatientSide = 'patient_right' | 'patient_left';
|
||||
|
||||
/**
|
||||
* Upper arch in chart order: patient's RIGHT (18) → midline → patient's LEFT (28).
|
||||
* That is the drawn left-to-right layout, which is the mirror of the patient's own sides.
|
||||
* Do not read a tooth position off this array by index — use `toFdi()`, which owns the
|
||||
* side convention.
|
||||
* Upper arch in chart order: patient's RIGHT (18) → midline → patient's LEFT (28) — the drawn
|
||||
* layout, which mirrors the patient's own sides. Never read a position off this array by
|
||||
* index; use `toFdi()`, which owns the side convention.
|
||||
*/
|
||||
export const FDI_UPPER_ARCH_ORDER = [
|
||||
'18',
|
||||
@@ -68,12 +67,9 @@ export function isFdiTooth(value: unknown): value is string {
|
||||
}
|
||||
|
||||
/**
|
||||
* Clean up a tooth code the extraction model echoed back, before it is matched.
|
||||
*
|
||||
* The model is transcribing Persian speech, so it can hand back "۲۶" in Persian digits or
|
||||
* "2 6" from a digit-by-digit dictation. Neither matches an FDI code literally, and a
|
||||
* near-miss here does not fail loudly — the tooth quietly turns into "not understood".
|
||||
* Returns '' for anything that is not a string.
|
||||
* Clean up a tooth code the model echoed back. It is reading Persian speech, so it can hand
|
||||
* back "۲۶" or "2 6" from digit-by-digit dictation; neither matches literally, and the
|
||||
* near-miss does not fail loudly — the tooth just turns into "not understood".
|
||||
*/
|
||||
export function normalizeFdiCode(value: unknown): string {
|
||||
if (typeof value !== 'string') return '';
|
||||
@@ -114,9 +110,8 @@ export function teethBetweenInclusive(a: string, b: string): string[] | null {
|
||||
/**
|
||||
* Arch + patient side + position (1 = central incisor … 8 = third molar) → FDI code.
|
||||
*
|
||||
* This function is the single place the patient-right convention lives. Getting it
|
||||
* backwards mirrors every quadrant and produces a valid-looking code for the wrong tooth,
|
||||
* which no schema check can catch — hence the exhaustive test coverage.
|
||||
* The single place the patient-right convention lives. Getting it backwards mirrors every
|
||||
* quadrant into a valid-looking code for the wrong tooth, which no schema check can catch.
|
||||
*/
|
||||
export function toFdi(
|
||||
arch: Arch,
|
||||
@@ -135,8 +130,8 @@ export function toFdi(
|
||||
}
|
||||
|
||||
/**
|
||||
* Sort teeth along the arch, not lexically — a bridge reads 16-15-14, and 11 sits beside
|
||||
* 21 across the midline. Teeth from another arch (or unknown) sort to the end, stably.
|
||||
* Along the arch, not lexically — a bridge reads 16-15-14, and 11 sits beside 21 across the
|
||||
* midline. Teeth from another arch sort to the end, stably.
|
||||
*/
|
||||
export function sortInArchOrder(teeth: readonly string[]): string[] {
|
||||
if (teeth.length === 0) return [];
|
||||
|
||||
Reference in New Issue
Block a user