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:
@@ -18,18 +18,14 @@ export type ToothResolution = {
|
||||
|
||||
/** Everything here parses untrusted model output, so nothing may throw. */
|
||||
function normalizedFdi(intent: ToothIntent): string {
|
||||
// Same normalisation the wire layer used to pick this branch, so the two cannot
|
||||
// disagree: '14 ' is tooth 14 through the treatment API and '۲۶' is tooth 26, and
|
||||
// neither may be reported as malformed here.
|
||||
// The same normalisation the wire layer used to pick this branch, so the two agree.
|
||||
return normalizeFdiCode((intent as { fdi?: unknown }).fdi);
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve one spoken tooth reference to an FDI code, or null.
|
||||
*
|
||||
* Never guesses and never clamps: a position of 9, a deciduous tooth, or a malformed
|
||||
* intent resolves to null so the caller can surface it as "not understood" rather than
|
||||
* silently selecting a neighbouring tooth.
|
||||
* Never guesses and never clamps: position 9, a deciduous tooth or a malformed intent all
|
||||
* resolve to null, so the caller surfaces "not understood" rather than silently selecting a
|
||||
* neighbouring tooth.
|
||||
*/
|
||||
export function resolveToothIntent(intent: ToothIntent): string | null {
|
||||
if (!intent || typeof intent !== 'object') return null;
|
||||
@@ -65,9 +61,8 @@ function unresolvedReason(intent: ToothIntent): UnresolvedItem['reason'] {
|
||||
intent.position < 1 ||
|
||||
intent.position > 8;
|
||||
if (positionBad) return 'position_out_of_range';
|
||||
// The position was understood, so the words were not the problem: the speaker never
|
||||
// said which quadrant. "دندون دو" names four teeth at once, and telling the
|
||||
// clinician it "could not be read" would send them looking for the wrong fault.
|
||||
// The position was understood; the quadrant was never said. "دندون دو" names four
|
||||
// teeth, so "could not be read" would send the clinician after the wrong fault.
|
||||
const archMissing = intent.arch !== 'upper' && intent.arch !== 'lower';
|
||||
const sideMissing =
|
||||
intent.side !== 'patient_right' && intent.side !== 'patient_left';
|
||||
@@ -78,11 +73,8 @@ function unresolvedReason(intent: ToothIntent): UnresolvedItem['reason'] {
|
||||
}
|
||||
|
||||
/**
|
||||
* The teeth still consistent with what *was* heard.
|
||||
*
|
||||
* Narrowed by whatever the clinician did say, so "دو" offers four and "دو بالا" offers
|
||||
* two. This is not a guess — it is the full set of readings, handed to the clinician to
|
||||
* choose from rather than picked on their behalf.
|
||||
* The teeth still consistent with what *was* heard — "دو" leaves four, "دو بالا" two. Not
|
||||
* a guess: the full set of readings, for the clinician to choose from.
|
||||
*/
|
||||
function quadrantCandidates(intent: ToothIntent): string[] {
|
||||
if (intent.kind !== 'positional') return [];
|
||||
@@ -109,11 +101,8 @@ function spokenOf(intent: ToothIntent): string {
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a list of spoken tooth references.
|
||||
*
|
||||
* Duplicates collapse — a clinician may name the same tooth twice in one sentence — and
|
||||
* anything unresolvable is reported rather than dropped, so the review sheet can show the
|
||||
* user exactly which words were not understood.
|
||||
* Duplicates collapse; anything unresolvable is reported rather than dropped, so the sheet
|
||||
* can show which words were not understood.
|
||||
*/
|
||||
export function resolveToothIntents(
|
||||
intents: readonly ToothIntent[],
|
||||
@@ -138,10 +127,8 @@ export function resolveToothIntents(
|
||||
const spoken = spokenOf(intent);
|
||||
const candidates =
|
||||
reason === 'tooth_missing_quadrant' ? quadrantCandidates(intent) : [];
|
||||
// Only dedupe items we can actually tell apart. Without `spoken`, two distinct lost
|
||||
// references would collapse into one blank review row and a tooth would vanish. The
|
||||
// candidates are part of the identity: the same word with a different arch heard
|
||||
// offers a different choice.
|
||||
// Only dedupe what we can tell apart: without `spoken`, two lost references collapse
|
||||
// into one blank row and a tooth vanishes. Candidates are part of the identity.
|
||||
if (spoken) {
|
||||
const key = `${spoken}::${reason}::${candidates.join(',')}`;
|
||||
if (seenUnresolved.has(key)) continue;
|
||||
|
||||
Reference in New Issue
Block a user