API routes or public interfaces are documented

Undocumented API routes are a maintenance hazard: a developer adding a new caller must read the full implementation to understand the expected request shape, authentication requirements, and error responses. At scale, this creates integration bugs and prevents safe independent development. ISO 25010 maintainability.analysability and reusability both degrade. Projects with 10+ API routes and zero documentation force every integration point to be reverse-engineered from implementation details — the kind of friction that produces subtle API misuse bugs.

Add a brief comment block to each API route describing its purpose, accepted input, and response shape:

// app/api/submissions/route.ts
/**
 * POST /api/submissions
 * Accepts an audit_telemetry JSON payload, validates schema,
 * computes scores, and stores in the submissions table.
 *
 * Body: AuditTelemetryPayload (see lib/types/telemetry.ts)
 * Returns: { submission_id: string, score: number }
 * Errors: 400 (invalid payload), 422 (validation failed)
 */
export async function POST(req: Request) { ... }

For larger APIs, generate an OpenAPI spec from your Zod schemas using zod-to-openapi — you get documentation and runtime validation from a single source of truth.