1---2name: oc-conventions3description: "Trigger: writing production code or tests, applying test naming/assert style, extracting constants, placing DTOs or characterization tests. Andres's personal code and test conventions."4license: MIT5metadata:6 source: https://skillmd.com/skills/andresnator/oc-conventions7 author: andresnator8 status: in-progress9 version: "3.1.1"10---1112# Code Conventions1314## Intent1516- **Goal:** Apply Andres's code and test conventions.17- **Limits:** Defaults for new code and repos without an established convention; when the target repo consistently follows another convention, the repo wins. Never churn diffs only to apply a soft preference.18- **Fails if:** Tests assert tautologically against their own constants; characterization tests mix with intent-revealing unit tests.1920## Context2122- **Reads:** The code under change, the repo's existing conventions.23- **Never reads:** none24- **Persona:** Pragmatic implementer.25- **Scope:** Load when writing production code or tests. Not for documentation, prose artifacts, or infrastructure config with no code. Planners route it by name via `oc-routing` without loading this body.2627## Expectations2829- **Scenarios:**30 - WHEN writing a plan or design document THEN record the detected language and tool versions with evidence (e.g. `java.version` in `pom.xml`, `typescript` in `package.json`) so the implementer can fetch version-correct documentation.31- **Done means:** Code and tests follow the Method rules or the repo's winning convention; any deviation is named in the plan, design, or summary.32- **Quality needs:** Single Responsibility and Open-Closed carry weight. Introduce interfaces or dependency inversion only for real variation, test seams, or architectural boundaries, never as SOLID dogma (see the `dip` lens in `oc-refactor-lens` `references/lenses.md`).3334## Method3536### Production code3738- **No magic literals:** extract hardcoded numbers and strings into named constants placed where tests can reuse them. Tests reuse them for fixtures and setup; when the constant IS the behavior under test, assert against the expected literal value.39- **Top-level DTOs:** DTOs and helper types are independent top-level classes/files, never inner or nested classes (Java), even when only one private method uses them. In TS, exported types in their own module following the repo layout.40- **Stepdown order (soft):** code reads top-down; private methods appear in the order they are called.4142### Tests4344- **Naming:** `should{Behavior}When{Condition}` or `when{X}Then{Y}`. Never Given-When-Then in the name.45- **Section markers:** every non-trivial test body is split with `// Given`, `// When`, `// Then` comments. They delimit phases; they are not explanatory comments.46- **Unified asserts:** fluent single-entry assertions: AssertJ `assertThat` in Java, `expect` in TS.47- **Whole-object asserts:** for complex objects or DTOs with many fields, assert the full object (`usingRecursiveComparison()` or ApprovalTests in Java, `toMatchObject`/`toMatchSnapshot` in Vitest/Jest), never a cascade of field-by-field asserts. Prefer structured comparison over raw snapshots when golden-master fragility hurts.48- **Characterization tests live apart:** a dedicated class/file per unit, `{ClassName}CharacterizationTest` (Java) or `<name>.characterization.test.ts` (TS). They are a permanent regression net.4950### Resources5152- `assets/examples/OrderServiceTest.java`: Java test with G/W/T sections, `assertThat`, recursive comparison, and a separate characterization class note.53- `assets/examples/order-service.test.ts`: Vitest test with G/W/T sections and `toMatchObject`.