Hot Take: Architecture Documents That Don't Specify Scope Are Pseudocode

TLDR

Writing architectural documentation that describes component behavior using implicit variable references (e.g., "checks if $X < \text{pageWidth} / 2$") without specifying parameter signatures leads directly to ReferenceError bugs in JavaScript applications. Documentation must explicitly state function signatures, parameter origins, and execution scope to serve as implementable specifications rather than high-level pseudocode.

Specification Type	Variable Origin Documentation	Implementation Risk	Quality Level
Implicit Behavioral Prose	Omitted ("Uses pageWidth")	High (ReferenceError risk)	High-Level Pseudocode
Explicit Parameter Signature	Explicit (fn(regions, numCols, pageWidth))	Zero (Unambiguous contract)	Production Specification

---

Technical analysis: the ambiguity of behavioral prose

A sentence in a design document stating "The function compares region.x to pageWidth / 2" leaves execution context open to four incompatible interpretations:

1. pageWidth is passed as a function parameter.
2. pageWidth is read from a module-level variable.
3. The function is nested inside a closure that captures pageWidth.
4. pageWidth is a property on an object argument.

When implemented as a module-level function without closure access, option 3 fails with a ReferenceError.

---

Remediation standard: explicit signature specifications

Specify function signatures explicitly in technical documentation:

/**
 * Correct Architectural Specification Standard:
 * 
 * _detectAutoZones(regions: Region[], numCols: number, pageWidth: number): Zone[]
 * - pageWidth: Viewport width (viewport.width || 612), passed from assemblePage()
 */
export function _detectAutoZones(regions, numCols, pageWidth) {
  const midpoint = pageWidth / 2;
  return regions.filter(r => r.bbox?.x < midpoint);
}

Rule of thumb: Document explicit function signatures and parameter origins for all helper functions in technical architecture specifications.