Rust Standards

Standards for Rust code.

Edition

• Use the latest stable edition (2021+)
• Set edition explicitly in Cargo.toml

Toolchain

• Follow the lint skill for formatting and linting — lintro runs rustfmt, clippy, cargo_audit, and cargo_deny as configured
• Treat clippy warnings as errors in CI (-D warnings)
• Customize formatting via rustfmt.toml where needed

Error Handling

• Use thiserror for library error types — derive structured, typed errors
• Use anyhow for application-level error propagation
• No .unwrap() in library code — use ? or return Result

• .expect() only with descriptive messages explaining the invariant:

  // Good
  let config = load_config().expect("config.toml must exist at startup");
  
  // Bad
  let config = load_config().unwrap();

• Implement std::fmt::Display for all custom error types

• Non-panicking .unwrap_or_default()/.unwrap_or() over trivial-arm matches:

  // Don't
  let count = match maybe_count {
      Some(n) => n,
      None => 0,
  };
  
  // Do
  let count = maybe_count.unwrap_or(0);

Type Patterns

• Prefer newtypes for domain concepts — struct UserId(u64) over bare u64
• Use impl Trait in argument position for flexibility; explicit generics in return position for clarity
• Derive Debug on all public types
• Derive Clone, PartialEq, Eq, Hash where semantically appropriate
• Prefer &str over String in function arguments; return String when ownership transfers

Unsafe

• unsafe blocks MUST include a // SAFETY: comment justifying soundness:

  // SAFETY: pointer is guaranteed non-null by the allocator contract,
  // and the lifetime is bounded by the enclosing scope.
  unsafe { ptr.as_ref() }

• Minimize unsafe surface area — encapsulate in safe abstractions
• Prefer safe alternatives (e.g., std::sync::Mutex over raw atomics) unless performance demands otherwise

Documentation

• /// doc comments on all public items (functions, types, traits, modules)

• Include code examples in doc comments for non-trivial APIs:

  /// Parse a duration string like "5s", "100ms", or "2m".
  ///
  /// # Examples
  ///
  /// ```
  /// use mycrate::parse_duration;
  ///
  /// let d = parse_duration("5s").unwrap();
  /// assert_eq!(d, std::time::Duration::from_secs(5));
  /// ```
  pub fn parse_duration(s: &str) -> Result<Duration> { ... }

• Use #![deny(missing_docs)] for library crates
• Module-level //! doc comments for crate and module overviews

Testing

• Unit tests in #[cfg(test)] mod tests within the same file
• Integration tests in tests/ directory
• Use #[should_panic(expected = "...")] for expected panics
• Consider proptest or quickcheck for property-based testing where valuable
• Use assert_eq! and assert_ne! over bare assert! for better error messages

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parse_duration_seconds() {
        let d = parse_duration("5s").unwrap();
        assert_eq!(d, Duration::from_secs(5));
    }

    #[test]
    #[should_panic(expected = "invalid format")]
    fn parse_duration_rejects_garbage() {
        parse_duration("not_a_duration").unwrap();
    }
}

Dependencies

• Keep the dependency tree minimal — every dependency is an audit and supply chain surface
• Run vulnerability scanning via lintro (uv run lintro chk includes cargo_audit and cargo_deny)
• Pin versions in workspace Cargo.toml for multi-crate workspaces
• Prefer well-maintained crates with active maintainers and good documentation

Patterns

• Prefer impl blocks over free functions for associated behavior
• Use the builder pattern for types with many optional fields
• Prefer iterators and combinators over manual loops where readability permits

• let-else over nested if let pyramids:

  // Don't
  if let Some(user) = lookup(id) {
      if let Some(email) = user.email {
          send(email);
      }
  }
  
  // Do
  let Some(user) = lookup(id) else { return };
  let Some(email) = user.email else { return };
  send(email);

• .find()/.position()/.any() over manual index loops:

  // Don't
  let mut idx = None;
  for (i, item) in items.iter().enumerate() {
      if item.id == target {
          idx = Some(i);
          break;
      }
  }
  
  // Do
  let idx = items.iter().position(|item| item.id == target);

• matches!() for pattern booleans:

  // Don't
  let is_ready = match state {
      State::Ready => true,
      _ => false,
  };
  
  // Do
  let is_ready = matches!(state, State::Ready);

• Use #[must_use] on functions whose return value should not be ignored
• Prefer From/Into implementations over ad-hoc conversion methods

Linting

Follow the lint skill for linting and formatting workflow.