quality baseline
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user