prometeu-runtime/docs/STYLE.md

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.