mirror of
https://github.com/storytold/materialcraft.git
synced 2026-11-19 05:50:57 +01:00
Add Rust code style guidelines
This commit is contained in:
1 parent
3133062968
commit
6b517db158
3 files changed
+80
-35
No files matched your search
@@ -72,7 +72,7 @@ repository's infrastructure (xtask, automation, packaging, docking, theme) was c
|
||||
The goal is full parity with the professional node-based material workflow (the same panels,
|
||||
menus, node library, parameters, shortcuts and file conventions) with better performance, every
|
||||
feature drivable by agents, and builds for Windows, macOS, Linux, FreeBSD and the web. Read this
|
||||
file first, then `docs/`.
|
||||
file first, then [CODE_STYLE.md](CODE_STYLE.md) before editing or reviewing code, then `docs/`.
|
||||
|
||||
## 1. Orientation (5 minutes)
|
||||
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
# Code style
|
||||
|
||||
Style conventions for MaterialCraft's Rust code.
|
||||
Read alongside [AGENTS.md](AGENTS.md) for repository requirements.
|
||||
|
||||
## Naming and Rust conventions
|
||||
|
||||
- Use descriptive names that explain purpose; include units where useful. Avoid misleading names
|
||||
and abbreviations whose meaning is unclear in context.
|
||||
- Follow Rust naming conventions: `snake_case` for functions, variables, fields, and modules;
|
||||
`UpperCamelCase` for types and traits; `SCREAMING_SNAKE_CASE` for constants and statics.
|
||||
- Conventional Rust names are not cryptic abbreviations. Keep names such as `fmt`, `iter`, `len`,
|
||||
`args`, `err`, `id`, and `ui` when their meaning is clear. Do not expand them just to make them
|
||||
longer.
|
||||
- Keep standard file and directory names such as `lib.rs`, `main.rs`, `mod.rs`, `src`, `tests`,
|
||||
`examples`, and `benches`. Rust keywords such as `mut`, `ref`, `impl`, and `mod` are language
|
||||
syntax, not naming problems.
|
||||
- Short names are appropriate in a clear local context: `i` for an index, `x` and `y` for
|
||||
coordinates, `w` and `h` for image dimensions, and conventional generic parameters such as `T`.
|
||||
Use more descriptive names when scope or ambiguity makes those hard to follow.
|
||||
|
||||
## Magic numbers
|
||||
|
||||
- Give non-obvious limits, thresholds, sizes, and tuning values descriptive named constants
|
||||
instead of leaving unexplained numeric literals in the code.
|
||||
- Name constants for their purpose, with units where useful, rather than for their literal value.
|
||||
Keep them in the narrowest useful scope.
|
||||
- Reuse an existing constant when it represents the same concept. Equal numeric values alone do
|
||||
not mean two concepts should share a constant.
|
||||
- Explain the origin or rationale of non-obvious coefficients and tolerances in a short comment.
|
||||
Use standard library constants for standard mathematical values.
|
||||
- Keep literals inline when their role is clear, such as zero initialization, incrementing by one,
|
||||
or dividing by two to find a midpoint. Do not introduce names such as `ZERO` or `TWO` that add
|
||||
no meaning.
|
||||
- Apply this guidance to tests too; clear fixture values and expected results can remain literal.
|
||||
|
||||
## Formatting and spacing
|
||||
|
||||
- Let `cargo fmt` and the repository's [rustfmt.toml](rustfmt.toml) handle mechanical formatting.
|
||||
Do not introduce a competing indentation or line-wrapping convention.
|
||||
- Use one blank line between distinct logical steps: input preparation, validation, computation,
|
||||
mutation, and result construction.
|
||||
- Keep closely related statements together. Do not add a blank line after every declaration or
|
||||
fragment a single operation with extra spacing.
|
||||
- Put a blank line after a multiline early-exit guard, including `if` and `let ... else`, before
|
||||
the next statement.
|
||||
- Put a blank line before a comment introducing a new step, with no blank line between the
|
||||
comment and the code it explains.
|
||||
- Keep documentation and attributes attached to their declarations.
|
||||
- Separate function definitions with one blank line. Avoid extra empty lines just inside braces
|
||||
or between every field, argument, or statement.
|
||||
- In tests, separate preparation, action, and verification with blank lines when those phases
|
||||
are distinct; keep related assertions together.
|
||||
|
||||
## Source organization
|
||||
|
||||
- Give each struct or enum its own source file, with its implementation beside it. Use the full
|
||||
type name in `snake_case`, such as `mesh_curvature_settings.rs` for `MeshCurvatureSettings`.
|
||||
- Preserve conventional crate roots and module entry points such as `lib.rs`, `main.rs`, and
|
||||
`mod.rs`. Follow the command and node module placement required by `AGENTS.md`.
|
||||
- Prefer singular folder names for new domain modules, such as `map`, `setting`, or `tracing`.
|
||||
Keep standard Rust directories and repository-mandated paths unchanged.
|
||||
- Group related types into focused modules rather than collecting unrelated types in one large file.
|
||||
- Apply these preferences to new types and source organization changes within scope. Do not
|
||||
reorganize unrelated existing code to enforce them.
|
||||
|
||||
## Comments
|
||||
|
||||
- Explain intent or a non-obvious constraint rather than narrating the code.
|
||||
- Use short `//` comments. Avoid block comments and wrapped prose in ordinary implementation
|
||||
comments; adjacent comment lines should each express a concise point.
|
||||
- Do not add trailing punctuation to ordinary code comments.
|
||||
- Preserve explanations of guards and invariants. Remove stale or redundant comments without
|
||||
losing necessary rationale.
|
||||
- API documentation, required license headers, and examples may use conventional multiline
|
||||
formatting and punctuation.
|
||||
- Apply the same comment guidance to production code and tests.
|
||||
@@ -8,7 +8,7 @@ Use these preferences when reviewing and improving a PR. Follow repository requi
|
||||
- Review-only requests call for findings; requests to fix or improve also authorize focused local edits
|
||||
- A review may conclude that no changes are needed. If the PR meets the applicable standards and no actionable issues are found, leave it unchanged. Do not invent findings, add unnecessary tests, or make edits merely to produce a diff. Report what was checked and any remaining validation limits
|
||||
- Apply all review standards across the entire affected method, including existing code and relevant tests
|
||||
- Complete naming, spacing, and comment cleanup throughout it
|
||||
- Read and apply [CODE_STYLE.md](../CODE_STYLE.md) throughout that scope
|
||||
- Make additional correctness or performance changes when supported by evidence and appropriate validation
|
||||
- Separate substantial changes that address an independent problem, explaining why
|
||||
- Apply the same scope to standalone functions and inspect relevant callers when verifying behavior
|
||||
@@ -27,6 +27,7 @@ Use these preferences when reviewing and improving a PR. Follow repository requi
|
||||
## Optimization and simplicity
|
||||
|
||||
- Prefer the smallest complete solution that is efficient and easy to understand
|
||||
- Keep control flow direct and share repeated logic when it makes the code simpler
|
||||
- Look for repeated calculations, expensive iterations, unnecessary allocations, and redundant data access
|
||||
- For loops, batches, and streaming operations, trace allocations and buffer lifetimes across multiple iterations, including outputs retained from earlier iterations. Identify work that belongs once per operation rather than once per item, using the full selection when making retention decisions
|
||||
- Consider caching, batching, and parallelism when measurements justify their complexity and memory cost
|
||||
@@ -35,39 +36,6 @@ Use these preferences when reviewing and improving a PR. Follow repository requi
|
||||
- Check what the compiler already optimizes before replacing clear arithmetic with micro-optimizations
|
||||
- Avoid speculative optimization, unnecessary dependencies, and abstractions that add more code than clarity
|
||||
|
||||
## Clarity, naming, and spacing
|
||||
|
||||
- Clean up the functions or methods being changed and their relevant tests within the scope above
|
||||
- Use descriptive names that explain purpose; include units where useful
|
||||
- Avoid cryptic abbreviations, misleading names, and unexplained production constants
|
||||
- Keep control flow direct and share repeated logic when it makes the code simpler
|
||||
- Use a single blank line to separate logical steps, such as input preparation, validation, computation, mutation, and result construction, when those steps are distinct
|
||||
- Keep closely related statements together; avoid spacing that fragments a single operation or inserts a blank line after every declaration
|
||||
- Put a blank line after a multiline early-exit guard, including `if` and `let ... else`, before the next statement
|
||||
- Keep comments attached to the code they explain; put a blank line before a comment introducing a new step, with no blank line between the comment and that step
|
||||
- Keep documentation and attributes attached to their declarations
|
||||
- Separate function definitions with one blank line; avoid extra empty lines immediately inside braces or between every field, argument, or statement
|
||||
- Group tests into preparation, action, and verification with blank lines where those phases are distinct; keep related assertions together
|
||||
- Apply this spacing consistently throughout affected functions, methods, and tests, and follow the repository's formatter for mechanical formatting
|
||||
|
||||
## Source organization
|
||||
|
||||
- Keep each class, enum, or struct in its own source file, with its implementation beside it
|
||||
- Spell out the full type name in the filename; use the language's filename convention, such as `mesh_curvature_settings.rs` for `MeshCurvatureSettings` in Rust
|
||||
- Use singular folder names, such as `map`, `setting`, or `tracing`
|
||||
- Group related types into focused modules and share helpers where useful without collecting unrelated types into one large file
|
||||
- Apply these preferences to new types and source organization changes within scope; follow mandatory repository layout rules and leave unrelated existing structure alone
|
||||
|
||||
## Comments
|
||||
|
||||
- Use short, single-line comments; adjacent comment lines should each express a concise point
|
||||
- Avoid block comments and wrapped prose in ordinary implementation comments
|
||||
- Explain intent or a non-obvious constraint rather than narrating the code
|
||||
- No trailing punctuation on ordinary code comments
|
||||
- Preserve explanations of guards and invariants; remove stale or redundant comments without losing necessary rationale
|
||||
- API documentation, required license headers, and examples may use their conventional multiline formatting and punctuation
|
||||
- Apply these standards to both production code and tests
|
||||
|
||||
## Validation and reporting
|
||||
|
||||
- Run relevant tests and required repository checks with the project's expected toolchain
|
||||
|
||||
Reference in new issue
Block a user