Pedro M. de Echanove Pasquin
9b99a18e26
code_style_guide.md was the generic C++ formulation of the Modified Allman style: it mandated camelCase for functions (every function in this crate is Rust snake_case, and rustc warns otherwise), three of its five examples taught try/catch brace placement for a construct Rust does not have, all examples were C++, and it instructed saving a .clang-format that does not exist and would not format Rust anyway. Its final YAML block was also missing the closing fence, so renderers swallowed the tail of the document. Since README defers to CONTRIBUTING and CONTRIBUTING defers here for the full rules, the contributor path terminated in the one document that contradicted the code.
Rewrite it for Rust: same principles (tabs, opening brace on its own line, compact "} else {", spaces inside non-empty parentheses), plus the rules the code follows but no document stated — snake_case for functions and variables, spaces inside non-empty attribute brackets, no spaces inside generics, aligned columns, comments in English. Examples are now idiomatic Rust: if/else, match, Result with the ? operator in place of try/catch, if let, struct + impl with attributes. The file declares itself the canonical reference, with CONTRIBUTING's bullets as the summary.
Replace the .clang-format section with the verified rustfmt situation: rustfmt cannot express this style (no option exists for spaces inside parentheses or attribute brackets, the brace-style options are nightly-only, and even on nightly Allman opening braces cannot combine with a compact "} else {"). Ship a rustfmt.toml with disable_all_formatting = true — a stable option, verified a no-op on rustfmt 1.8.0 — so an accidental cargo fmt or editor format-on-save can no longer rewrite the tree.
137 lines
3.6 KiB
Markdown
Executable File
137 lines
3.6 KiB
Markdown
Executable File
# Code Style Guide
|
|
|
|
This project follows a **Modified Allman** brace and formatting style, applied to Rust. It prioritizes **visual clarity, symmetry, and logical separation of blocks** over strict line compactness.
|
|
|
|
This file is the canonical style reference; the style bullets in [CONTRIBUTING.md](CONTRIBUTING.md) are a summary of it.
|
|
|
|
---
|
|
|
|
## Key principles
|
|
|
|
- Indentation with **tabs** (width = 4).
|
|
- **Opening braces `{`** start on their own line — for `fn`, `impl`, `struct`, `enum`, `trait`, `mod`, `if`, `for`, `while`, `loop` and `match`.
|
|
- **`} else {`** and **`} else if … {`** stay on the same line for compact flow.
|
|
- **Spaces inside parentheses only when non-empty:**
|
|
- `( arg1, arg2 )`
|
|
- `main()`
|
|
- **Spaces inside attribute brackets only when non-empty:** `#[ derive( Clone, Debug ) ]`, `#[ cfg( test ) ]`.
|
|
- **No spaces inside generics:** `Vec<String>`, `Option<i32>`, `Element<Msg>`.
|
|
- **Types, traits, and enum variants:** PascalCase.
|
|
- **Functions, methods, variables, and modules:** snake_case (the Rust convention; `rustc` warns on anything else).
|
|
- **Constants and statics:** UPPER_CASE_WITH_UNDERSCORES.
|
|
- **Aligned columns** in consecutive struct fields, match arms, or `let` groups where it aids scanning.
|
|
- **Comments in English**, only where the code cannot say it itself.
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### `if / else` structure
|
|
|
|
```rust
|
|
if condition
|
|
{
|
|
do_something();
|
|
} else if other_condition {
|
|
do_other_thing();
|
|
} else {
|
|
do_something_else( arg1, arg2 );
|
|
}
|
|
```
|
|
|
|
### `match` structure
|
|
|
|
```rust
|
|
match points.len()
|
|
{
|
|
0 => None,
|
|
1 => Some( points[0].value ),
|
|
n => Some( total / n as f32 ),
|
|
}
|
|
```
|
|
|
|
### Error handling
|
|
|
|
Rust has no `try / catch`; recoverable errors travel as `Result` and propagate with `?`. The block style applies to the `match` when a result is handled in place:
|
|
|
|
```rust
|
|
fn load_config( path: &Path ) -> Result<Config, ConfigError>
|
|
{
|
|
let text = std::fs::read_to_string( path )?;
|
|
match toml::from_str( &text )
|
|
{
|
|
Ok( cfg ) => Ok( cfg ),
|
|
Err( e ) => Err( ConfigError::Parse( e ) ),
|
|
}
|
|
}
|
|
```
|
|
|
|
`if let` follows the same brace rules as `if`:
|
|
|
|
```rust
|
|
if let Some( ( rgba, w, h ) ) = icon( "general/right" )
|
|
{
|
|
it = it.trailing_icon( rgba, w, h );
|
|
}
|
|
```
|
|
|
|
### Structs, impls, and attributes
|
|
|
|
```rust
|
|
#[ derive( Clone, Debug ) ]
|
|
pub struct DataPoint
|
|
{
|
|
value: f32,
|
|
label: String,
|
|
}
|
|
|
|
impl DataPoint
|
|
{
|
|
pub fn new( value: f32, label: impl Into<String> ) -> Self
|
|
{
|
|
Self
|
|
{
|
|
value,
|
|
label: label.into(),
|
|
}
|
|
}
|
|
|
|
pub fn scaled( &self, factor: f32 ) -> f32
|
|
{
|
|
if factor <= 0.0
|
|
{
|
|
self.value
|
|
} else {
|
|
self.value * factor
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### `main()` function
|
|
|
|
```rust
|
|
fn main()
|
|
{
|
|
let analyzer = DataAnalyzer::new( "results.csv" );
|
|
|
|
if let Err( e ) = analyzer.process_and_report()
|
|
{
|
|
eprintln!( "Error: {e}" );
|
|
std::process::exit( 1 );
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Tooling: do not run `cargo fmt`
|
|
|
|
`rustfmt` cannot express this style, so **never run `cargo fmt` on this codebase** — it would rewrite every file into the default style. Specifically:
|
|
|
|
- There is **no rustfmt option for spaces inside parentheses or attribute brackets** (the historical `spaces_within_parens` options were removed from rustfmt).
|
|
- The item brace styles (`brace_style`, `control_brace_style`) are **unstable, nightly-only** options.
|
|
- Even on nightly, the combination of Allman opening braces with a compact `} else {` is not representable: `control_brace_style = "AlwaysNextLine"` also pushes `else` onto its own line.
|
|
|
|
The repository ships a `rustfmt.toml` containing only `disable_all_formatting = true`, so an accidental `cargo fmt` — or an editor with format-on-save wired to rustfmt — is a no-op instead of a 40 000-line diff. Style is enforced by review, not by a formatter.
|