Code style

Style conventions for MaterialCraft's Rust code. Read alongside 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.

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.

Let cargo fmt and the repository's 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.

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.

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.