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:
2026-08-21 23:46:56 +08:00
parent 562ef2ae6e
commit dc10d8dbe3
26 changed files with 155 additions and 306 deletions

View File

@@ -2000,8 +2000,7 @@ export function TreatmentWorkspace({
const nextDetails = [...detailsRef.current, detail];
setDetails(nextDetails);
// persistDraft reads detailsRef, and setDetails has not rendered yet. The codebase
// already writes this ref imperatively after a save for the same reason.
// persistDraft reads detailsRef, and setDetails has not rendered yet.
detailsRef.current = nextDetails;
setActiveDetailId(detail.clientId);
setEntryStep('treatment');
@@ -2045,19 +2044,16 @@ export function TreatmentWorkspace({
const updatedLabCases = [...labCaseDrafts, draft];
setLabCaseDrafts(updatedLabCases);
// Every other path that creates a lab draft persists it immediately, and the
// autosave effect only watches `details`. Left in state alone, the destination
// lab, the due date and the whole prosthesis map vanish on the next reload —
// silently, because the detail itself does survive.
// Autosave only watches `details`, so a lab draft left in state alone loses the
// lab, the due date and the prosthesis map on reload — silently, because the
// detail itself survives.
void (async () => {
try {
const saved = await persistDraft({ force: true });
// persistDraft returns a *preview* treatment rather than saving when the
// details are not persistable — one blank detail, the kind the workspace opens
// with, is enough. A preview's detail id falls back to the client id, so
// posting lab cases against it would send the server an id it has never seen
// and fail the whole save. Check what came back, not the precondition, so this
// holds for every early return persistDraft has.
// persistDraft returns a *preview* when the details are not persistable — one
// blank detail is enough — and a preview's detail id falls back to the client
// id. Check what came back, not the precondition, so this holds for every early
// return persistDraft has.
const savedDetail = saved.details.find((d) => d.clientId === detail.clientId);
if (!savedDetail?.id || savedDetail.id === detail.clientId) return;
await persistLabCases(saved, updatedLabCases);