# Prometeu Runtime — Style Guide

This document defines the baseline code style and commenting policy for the reset cycle.

Goals:
- Professional, consistent, and readable code.
- Deterministic and actionable error messages.
- English-only comments and docs.

General principles
------------------
- Rust edition: use the crate’s configured edition (currently 2024 across new crates).
- Keep modules small and cohesive; prefer explicit interfaces over glob imports.
- Avoid premature abstraction; refactor when duplication becomes meaningful.

Comments and documentation
--------------------------
- Language: English only.
- Use `///` for public API documentation comments and module-level docs (`//!`).
- Use `//` for local/internal notes that do not need to surface in docs.
- Write comments that explain “why,” not “what” (the code already shows “what”).
- Keep comments up to date with behavior; outdated comments should be removed or fixed.

Error messages
--------------
- Be clear, actionable, and deterministic.
- Include the failing condition and the expected invariant when useful.
- Avoid leaking internal jargon; prefer user-understandable phrasing.
- Do not rely on timing or nondeterminism for error reproduction.

Naming conventions
------------------
- Crates and modules: `kebab-case` for crates, `snake_case` for modules and files.
- Types and traits: `PascalCase` (e.g., `VirtualMachine`, `BytecodeLoader`).
- Functions, methods, and variables: `snake_case`.
- Constants and statics: `SCREAMING_SNAKE_CASE`.
- Avoid abbreviations unless they are widely recognized (e.g., `pc`, `vm`).

Documentation structure
-----------------------
- Each public crate should have a crate-level docs section describing its purpose.
- Prefer small examples in docs that compile (use `rustdoc` code blocks when feasible).
- Keep module/file headers brief and focused.

Formatting and linting
----------------------
- `cargo fmt` is the source of truth for formatting.
- `cargo clippy` should run clean on the default toolchain. Where a lint is intentionally
  violated, add a focused `#[allow(lint_name)]` with a short rationale.