Files
2026-11-12 11:06:58 -05:00

122 lines
8.4 KiB
Markdown

---
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
last_mapped_at: 2026-11-12
---
# Coding Conventions
**Analysis Date:** 2026-11-12
## Naming Patterns
**Files:**
- Use PascalCase C# filenames matching the principal type: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`.
- Use snake_case Python modules and `test_*.py` regressions: `tools/extractors/sound_bank.py`, `tests/test_actor_contact.py`.
- Keep shell entry points under `scripts/`, using descriptive hyphenated names such as `scripts/test-window-transitions.sh`.
**Functions:**
- Use PascalCase C# methods (`ReadVelocity`, `GenericWall`) as in `src/GamePort/Game/OriginalNormalContacts.cs`.
- Use snake_case Python functions (`export_sound_bank`, `validate_output`) as in `tools/extractors/sound_bank.py` and `tools/extractors/omt.py`.
- Name Python test methods `test_<behavior>`; `tests/test_extractors.py` names invalid-input cases explicitly.
**Variables:**
- Use camelCase C# parameters and locals, with explicit role names such as `headingUnits`, `oldHeading`, `carriedPlayer` in `src/GamePort/Game/OriginalNormalContacts.cs` and `src/GamePort/Program.cs`.
- Private C# fields do not uniformly use underscore prefixes; match the surrounding module (`src/GamePort/Assets/GamLevel.cs`).
- Python locals use snake_case; module constants use uppercase (`ROOT`, `ORIGINAL`, `CALLBACK_OPERANDS` in `tests/test_actor_contact.py`).
**Types:**
- Use PascalCase C# classes/records and `I`-prefixed interfaces, exemplified by `OriginalNormalContacts` and `IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`.
- Python uses PascalCase classes and frozen dataclasses for resource identity (`Reader`, `Entry`, `FormatError` in `tools/extractors/omt.py`).
## Code Style
**Formatting:**
- No tracked formatter or `.editorconfig` is detected in the mapped repository. Follow each file's existing style rather than assuming an enforced formatter (`GamePort.csproj`, `src/GamePort/Assets/GamLevel.cs`).
- C# generally uses four spaces, file-scoped namespaces and braces on separate lines; short guards and expression-bodied helpers are common. Some numerical modules and console tests use compact spacing (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`).
- Python uses four spaces, type annotations where useful, and compact reader helpers; quotation style varies (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`).
**Linting:**
- Dedicated C#/Python lint configurations are Not detected. `GamePort.csproj` enables nullable references, implicit usings and unsafe blocks; it does not declare warnings-as-errors or a separate analyzer package.
- Preserve explicit compile globs and shader copy rules in `GamePort.csproj`; test projects can compile production source directly, as in `tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`.
## Import Organization
**Order:**
1. C# explicit `System` namespaces precede project namespaces in `src/GamePort/Program.cs` and `tests/GamePort.ActorContactTests/Program.cs`.
2. Group runtime dependencies by namespace; implicit usings supply common base namespaces (`GamePort.csproj`).
3. Python standard library imports precede local tool imports. Tests insert the relevant tools directory into `sys.path` (`tests/test_extractors.py`, `tests/test_actor_contact.py`).
**Path Aliases:**
- No frontend-style aliases are applicable. Use `GamePort.Assets`, `GamePort.Game` and related C# namespaces; Python tool imports resolve from explicit local paths (`src/GamePort/Program.cs`, `tests/test_actor_contact.py`).
## Error Handling
**Patterns:**
- Fail malformed assets with contextual format exceptions, including offsets. Do not silently truncate or accept trailing bytes (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`).
- Reject unsupported recovered behavior explicitly with `NotSupportedException`; validate nonfinite values separately with argument exceptions (`src/GamePort/Game/OriginalNormalContacts.cs`).
- Keep entry-point failure reporting centralized: `src/GamePort/Program.cs` catches exceptions, writes to stderr and returns status 1.
- Resolve original asset names case-insensitively after direct lookup, reject `.`/`..`, and reject missing/ambiguous matches (`src/GamePort/Assets/AssetPath.cs`).
- Reject extraction output overlapping originals; preserve source hashes and archive identities in generated metadata (`tools/extractors/sound_bank.py`).
Representative bounded C# reader from `src/GamePort/Assets/GamLevel.cs`:
```csharp
public ReadOnlySpan<byte> Take(int length)
{
if (length < 0 || length > Remaining)
throw new InvalidDataException($"Truncated GAM at {Offset:x}");
var result = data.Slice(Offset, length);
Offset += length;
return result;
}
public uint U32() => BinaryPrimitives.ReadUInt32BigEndian(Take(4));
```
## Logging
**Framework:** Console output, with explicit application diagnostics; no hosted logging service is detected (`src/GamePort/Program.cs`, `src/GamePort/Application/DebugDiagnostics.cs`).
**Patterns:**
- Report fatal errors to `Console.Error`; expose inspection/smoke commands and readback paths through CLI options (`src/GamePort/Program.cs`).
- Tests print descriptive `PASS` messages and throw on failure (`tests/GamePort.ActorContactTests/Program.cs`).
- Persist verification scope and limitations in `docs/progress.md`, `docs/compatibility.md` and subsystem reports; console success alone does not establish whole-game equivalence.
## Comments
**When to Comment:**
- Explain original addresses, ownership, sampled field order and excluded behavior rather than restating arithmetic (`src/GamePort/Game/OriginalNormalContacts.cs`).
- Preserve concrete resource semantics: effect IDs are archive identities, and encoded audio preservation is separate from decoder support (`tools/extractors/sound_bank.py`).
- Keep recovered contracts distinct from approximations and runtime admission; `AGENTS.md` and `docs/checkpoint/actor-normal-contacts.md` make these evidence boundaries explicit.
**XML documentation / Python docstrings:**
- Use C# `/// <summary>` for bounded public contracts and interfaces (`src/GamePort/Game/OriginalNormalContacts.cs`).
- Use Python module/class docstrings for recovery purpose and failure semantics (`tools/extractors/omt.py`). JSDoc/TSDoc is Not applicable.
## Function Design
**Size:**
- Prefer focused components such as the ceiling/reflection helpers in `src/GamePort/Game/OriginalNormalContacts.cs`; no numerical line-count rule is detected. `src/GamePort/Program.cs` remains a substantial orchestration entry point.
**Parameters:**
- Use explicit vectors, typed state and named flags rather than hidden scene state in recovered algorithms (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`).
- Inject actor-owned accessors through interfaces where read order matters; do not cache values across callbacks without evidence (`IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`).
- Keep bounded readers over spans/bytes and explicitly choose endianness (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`).
**Return Values:**
- Return parsed records, typed state, or explicit metadata; throw for malformed/unsupported input (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/sound_bank.py`).
- Preserve float-store boundaries and intentional double intermediates in recovered math. Do not simplify formulas or clamp source values without evidence (`src/GamePort/Game/OriginalNormalContacts.cs`, `docs/checkpoint/dynamic-reclip.md`).
## Module Design
**Exports:**
- Keep asset decoding in `src/GamePort/Assets/`, recovered algorithms in `src/GamePort/Game/`, SDL interop in `src/GamePort/Platform/Sdl.cs`, and presentation in `src/GamePort/Application/`.
- Python tools expose importable parser/export functions as well as CLI-oriented modules (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`).
- Use `using`/disposal and explicit native ownership at runtime boundaries (`src/GamePort/Program.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`); follow the project requirement in `AGENTS.md`.
**Barrel Files:**
- Not detected / Not applicable. C# namespaces and project compile includes provide organization (`GamePort.csproj`).
- Project-local agent skill constraints: the configured agent-skill query is empty; the applicable project constraints are in `AGENTS.md`.
---
*Convention analysis: 2026-11-12*