> **Status note (2025-10-24):** Last edited 2025-10-24 · Archive after: Retain indefinitely as an engineering standard · Implementation window: Per Standard status (see Decision).

# Standard-001: Internal nomenclature standardisation

Formerly ADR-017. Reclassified as an engineering standard to keep ADRs scoped to
architectural or contract decisions.

Status: Active (2025-10-06)

## Context

Repeated refactors left the package with a patchwork of naming schemes. The canonical calibration modules now live in `core/venn_abers.py`, `core/interval_regressor.py`, and the plotting surface in `viz/plots.py`. Earlier compatibility wrappers lived under `legacy/_*.py` and emitted `DeprecationWarning` during the migration; they have now been retired, leaving `legacy/plotting.py` as the lone legacy surface while the public API remains unchanged. Transitional shims such as `core.py` still exist but are clearly marked, letting contributors infer intent without losing the public API guarantees documented in the README.【F:src/calibrated_explanations/core/venn_abers.py†L1-L120】【F:src/calibrated_explanations/core/interval_regressor.py†L1-L120】【F:src/calibrated_explanations/viz/plots.py†L1-L20】【F:src/calibrated_explanations/legacy/plotting.py†L1-L120】

## Decision

Adopt the following naming standards for all **non-public** code paths (tests and tooling included) while keeping the public API stable, explicitly preserving the WrapCalibratedExplainer contract (fit/calibrate/explain/predict routines, plotting helpers, and uncertainty/threshold options) without renames or deprecation notices:

1. **Module and package names** must use `snake_case`. Leading underscores are reserved for private transitional modules that are scheduled for removal. CamelCase file names are prohibited.
2. **Class names** use `PascalCase`; helper classes intended for local use should include a suffix clarifying scope (e.g. `...Helper`, `...Mixin`).
3. **Functions, methods, and module-level variables** use `snake_case`. Names signalling booleans should be prefixed with verbs such as `is_`, `has_`, or `should_`.
4. **Private attributes** use a single leading underscore. Double-underscore name mangling is limited to legacy code; new code MUST NOT introduce it outside of dataclass field defaults required by language constraints.
5. **Transitional shims** (e.g. deprecated modules kept for import compatibility) must include a `deprecated_` prefix or live in a `legacy` subpackage so that their status is self-evident.
6. **Utility modules** should be split by responsibility (e.g. `fs_utils`, `type_utils`) with names describing the primary concern. Cross-cutting helpers belong in a dedicated module with descriptive prefixes (`convert_`, `ensure_`, etc.).
7. **Configuration and schema identifiers** (plugin IDs, registry keys) follow dot-delimited lowercase paths (`core.explanation.factual`). Aliases should be documented in one location and deprecated with clear suffixes (e.g. `.legacy`).
8. **Documentation and ADRs** must reference canonical names and call out deprecated identifiers explicitly to avoid drift between prose and code.

## Consequences

- **Pros**: Predictable naming reduces onboarding friction, clarifies module ownership, and enables mechanical refactors (e.g. automated module moves) without repeated human review of naming choices.
- **Cons**: Renaming legacy files will touch many imports; coordinated updates and deprecation warnings are necessary to avoid churn for downstream users reading stack traces.
- **Neutral**: The public API remains untouched, but internal contributors must adhere to the new conventions and update style guides accordingly.

## Implementation notes

- Update the contributor documentation with a quick-reference table describing the naming rules.
- Introduce lint checks (Ruff `N8` rules or custom scripts) that fail when modules deviate from snake_case or when new double-underscore attributes appear.
- Ensure deprecation shims emit warnings explaining the new module names and pointing to migration guides.
- Plan renames in batches (per subpackage) to keep pull requests reviewable while moving toward full compliance.

## Status tracking

- 2025-10-06 – Ratified as **Accepted** following maintainer sign-off with
  preparatory guardrails targeting the v0.7.0 milestone.
- v0.7.0 – Ruff naming checks and double-underscore detectors run in
  non-blocking mode, CONTRIBUTING.md gains the quick-reference guide, and
  telemetry captures naming lint drift to size the remaining debt.
- v0.8.0 – Phase 2 renames move priority packages to canonical names with
  shims captured under `legacy/`, and CI surfaces warnings when new
  aliases appear outside the allowed namespace. Completed via the
  `core.interval_regressor`, `core.venn_abers`, and `viz.plots` moves in
  this release.
- v0.9.0 – Deprecated shims scheduled for removal are pruned, naming lint
  promotion to blocking status is completed on the release branch, and
  release notes document the surviving compatibility shims.
- v1.0.0-rc – Remaining transitional imports are removed, and the release
  candidate checklist verifies lint parity between `main` and the RC
  branch before freeze.
- v1.0.0 – Post-tag monitoring keeps the naming lint suite blocking and
  schedules quarterly audits of the legacy namespace to guard against
  regressions.