Code conventions

These conventions describe the patterns used throughout the TypeScript rewrite and the expectations that make changes easier to review. They complement the compiler, linter, and tests; they do not replace them.

Reuse before adding

Before adding a helper, utility, class, or new file, search the codebase for an existing abstraction that already performs the operation or can be extended cleanly.

Keep the change in the owning subsystem

A parser problem should normally be fixed in parser logic, a TeX problem in converters, and an algebra problem in algebra. Avoid compensating for a lower-level defect in several callers when the underlying representation or operation can be corrected once.

Prefer one clear return path

Many Nerdamer functions build a result in a variable named retval and return once at the end. This makes complicated symbolic branches easier to inspect while debugging.

function operation(x: Expression): Expression {
  let retval: Expression;

  if (x.isNUM()) {
    retval = handleNumber(x);
  } else {
    retval = handleSymbolic(x);
  }

  return retval;
}

function square(x: number): number {
  return x * x;
}

The goal is readable control flow, not a mechanical ban on every early return. Small guards and simple functions can stay simple.

Do not weaken types to make an error disappear

TypeScript is part of Nerdamer’s design. When a type error exposes a mismatch between parser entities, containers, expressions, or APIs, resolve the mismatch rather than broadening the type to any or forcing an unsafe cast.

Preserve parser-entity distinctions

Not every parsed value is an Expression. Equations, vectors, matrices, sets, collections, and dictionaries are real result types. Do not silently coerce one into an Expression merely to reuse an API unless that conversion is part of the documented behavior.

Use named constants and existing symbolic shortcuts

When the codebase already has a named constant, enum value, parser constant, or preconstructed symbolic shortcut, use it instead of repeating a magic string or constructing the same symbolic value ad hoc.

// Prefer the established project value when one exists.

const value = two();

// Avoid repeating an equivalent construction throughout the codebase.

const value = Expression.create(2);

This is especially useful for parser names, expression groups, operator names, common numeric values, and settings shared across modules.

Access modifiers should describe intended use

Do not make a method private simply because there is only one caller today. A method should be private when it belongs solely to the implementation of its declaring class. Keep reusable or subclass-facing behavior public or protected as appropriate.

Comments should survive the change

If you modify code that already has explanatory comments, preserve them or revise them so they remain true. Do not remove useful context simply because the implementation changed.

For new comments, explain the non-obvious reason or mathematical step rather than narrating the next line.

Tests should protect the behavior that failed

For a bug fix, add a targeted regression that reproduces the original failure directly. Prefer a small test that clearly states the expected mathematical or API behavior over a broad snapshot that could pass for the wrong reason.

Be conservative with files and exports

New files, barrel exports, and public symbols add complexity to the project. Introduce them when they clarify the structure or expose an API intended for ongoing support, not simply to make a local change appear cleaner.

Likewise, do not delete apparently unused code until you have checked for public exports, parser registration, string dispatch, reflection, compatibility hooks, test-only use, or library utilities.

Validate at the right levels

npm run typecheck
npm test
npm run build

Use targeted tests while iterating, then run the full checks before considering a change complete. If the change affects generated documentation or package exports, run the corresponding documentation or package-validation commands as well.

Quick review checklist