Skip to content

Comment cleanup pass on biometric-vault package #3

Description

@LiranCohen

Summary

The biometric-vault package has accumulated ~700+ comment lines that reference internal review iteration (Round-N FX: prefixes), narrate pre-fix vs. post-fix history, or expand single-sentence intent into multi-paragraph essays. This is noise — git history captures the fix narrative; comments should describe the current code's intent and constraints.

Scope

Files with the highest comment debt:

File Round-N / pre-fix references
src/lib/enbox/__tests__/biometric-vault.test.ts 70
src/lib/enbox/agent-store.ts 67
src/lib/enbox/biometric-vault.ts 61
src/lib/enbox/__tests__/agent-store.reset-blockers.test.ts 57
android/.../NativeBiometricVaultModule.kt 27
src/features/session/session-store.test.ts 26
src/features/session/session-store.ts 21
ios/.../RCTNativeBiometricVault.mm 16
(long tail across remaining package files) ~200

Problems with the Current Style

  • Review-cycle prefixes (// Round-15 F3:, // Round-9 F4:): meaningless to anyone not present for the original review.
  • Pre-fix narration (Pre-fix the helper logged a warning and returned 'true'...): explains code that no longer exists.
  • Multi-paragraph essays where one sentence would do: many comments restate the surrounding code instead of explaining intent.
  • Fictional spec tags (VAL-VAULT-028): there is no validation document the codebase ships; these tags don't resolve.
  • self-review tags: internal AI-cycle nomenclature.

Acceptance Criteria

  • Zero Round-N FX: / Round-N self-review: prefixes in the package.
  • No Pre-fix ... / pre-fix ... historical narration.
  • VAL-VAULT-XXX tags either resolve to a real, checked-in spec or are removed.
  • File / function header comments describe the what and why (intent, invariants, non-obvious constraints) — not the change history.
  • Multi-paragraph block comments collapsed to 1–3 lines unless they capture a non-obvious invariant or trade-off.
  • Crash-resilience / fail-CLOSED rationale stays — but framed as current constraints, not as patch notes.
  • Test files: prefer descriptive describe / it titles over inline narration; keep at most one short intent comment per test.

Out of Scope

  • Refactoring code structure (separate issues).
  • Renaming public APIs.

Notes

  • Commit messages and PR descriptions remain valid places for review-round nomenclature; they live in git history where it belongs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions