50 lines
2.1 KiB
Markdown
50 lines
2.1 KiB
Markdown
# 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.
|