Coding Rules for Rust: Types & Traits

[rcseacord]

Do any of these make sense as rules?

1. Prefer Explicit, Intent-Revealing Type Definitions

Rule: Use type aliases or newtypes (tuple structs) when they increase clarity or strengthen type safety.

Use a newtype when two quantities have the same underlying primitive but different semantics:

struct Meters(u32);
struct Seconds(u32);

Use a type alias when the semantic meaning is exactly the same as the underlying type:

type UserId = u64;

Rationale: Prevents accidental mixing of logically distinct values, improves safety, and assists API discovery.

2. Avoid Using impl Trait in Public Signatures (Except for Return Types)

Rule: In public APIs, do not use impl Trait in argument position; prefer explicit trait bounds.

Allowed (return position):

pub fn iter_names() -> impl Iterator<Item = String>;

Avoid in parameters:

// Less clear
pub fn process(x: impl Read) { ... }

// Preferred
pub fn process<R: Read>(x: R) { ... }

Rationale: Makes type relationships explicit and helps prevent breaking API changes.

3. Use Traits to Represent Capabilities, Not Categories

Rule: A trait should describe behavior, not a “type group.”

Bad example:

trait Vehicle {} // no behavior

Good example:

trait Drivable {
    fn drive(&mut self, km: u32);
}

Rationale: Traits are for polymorphism and abstraction of behavior, not tagging or inheritance.

4. Keep Traits Small and Focused

Rule: Prefer small cohesive traits (“single responsibility”). Avoid large, multipurpose trait collections.

Good:

trait Serialize { fn serialize(&self) -> String; }
trait Deserialize: Sized { fn deserialize(s: &str) -> Self; }

Avoid:

trait SerdeLike {
    fn serialize(&self) -> String;
    fn deserialize(s: &str) -> Self;
    fn version(&self) -> u32;
    ...
}

Rationale: Allows flexible composition, easier mocking, and fewer breaking changes.

5. Use Trait Bounds Conservatively

Rule: Do not over-constrain types in generics.

Avoid:

fn compute<T: Clone + Debug + Display>(x: &T) { ... }

Use only what you need:

fn compute<T: Clone>(x: &T) { ... }

Rationale: Reduces unnecessary coupling and makes the function more widely applicable.

6. Prefer #[derive] for Simple Traits

Rule: Where correct, use deriving for traits such as:

Copy, Clone

Debug

PartialEq, Eq

PartialOrd, Ord

Hash

Default

Example:

#[derive(Debug, Clone, PartialEq, Eq)]
struct Point { x: i32, y: i32 }

Rationale: Derivations are consistent, tested, and faster to maintain.

7. Only Implement Copy for Types With Clear "Copy Semantics"

Rule: A type should implement Copy only if copying it is clear, cheap, and intuitive.

Good candidates: numeric types, small POD structs.

Avoid for types that own resources (Vec, String, file handles, network sockets).

Rationale: Avoids surprising implicit duplication of data or resource operations.

8. Use Associated Types in Traits When There Is Only One Logical Output Type

Rule: Prefer associated types over type parameters when the implementer should fix one concrete type.

Example:

trait Graph {
    type Node;
    fn neighbors(&self, node: Self::Node) -> Vec<Self::Node>;
}

Rationale: More ergonomic; prevents type-parameter explosion.

9. Use Enums to Represent State Variants Explicitly

Rule: Prefer enumerations over implicit states represented by Option, booleans, or magic values.

Bad:

struct Connection {
    connected: bool,
}

Good:

enum ConnectionState { Connected, Disconnected }
struct Connection {
    state: ConnectionState,
}

Rationale: Enums encode invariants directly into the type system.

10. When Defining Error Types, Implement the Standard Error Traits

Rule: Your error type should implement:

Debug (required)

Display

std::error::Error

Example:

#[derive(Debug)]
enum MyError {
    Io(std::io::Error),
    Parse(String),
}

impl std::fmt::Display for MyError { ... }
impl std::error::Error for MyError {}

Rationale: Integrates cleanly with ?, anyhow, eyre, and error-chains.

11. Avoid Exposing Type Invariants Through pub Fields

Rule: Most types should encapsulate internal fields unless the invariant is trivial.

Avoid:

pub struct Range { pub start: i32, pub end: i32 }

Prefer:

pub struct Range { start: i32, end: i32 }
impl Range {
    pub fn new(start: i32, end: i32) -> Result<Self, RangeError> { ... }
}

Rationale: Prevents invalid states and helps maintain invariants.

12. Use From/Into for Conversions, Not Ad Hoc Methods

Rule: Use standard conversion traits instead of custom to_xxx() or from_xxx() names.

Example:

impl From<u32> for Duration {
    fn from(secs: u32) -> Self { Duration::from_secs(secs as u64) }
}

Rationale: This leverages the universal conversion ecosystem.

13. Do Not Overuse Trait Objects (dyn Trait)

Rule: Only use trait objects for runtime polymorphism, not simply to avoid generics.

Bad:

fn process(items: Vec<Box<dyn Display>>) { ... }

Better:

fn process<T: Display>(items: Vec<T>) { ... }

But use dyn Trait when you need heterogeneity:

let tasks: Vec<Box<dyn Task>> = vec![Box::new(ReadTask), Box::new(WriteTask)];

14. Ensure Trait Methods Form a Coherent Contract

Rule: A trait should specify behavioral invariants explicitly—even if only in documentation.

Example:

/// # Contract:
/// `pop()` must remove and return the *last* item.
/// `push()` must add an item to the *end* of the collection.
trait Stack { ... }

Rationale: Prevents ambiguous or surprising implementations.

15. Prefer Safer Type Representations (Avoid unsafe Struct Layout Unless Necessary)

Rule: Avoid repr(C) or repr(packed) unless absolutely required for FFI or specific memory layout.

Packed structs remove alignment guarantees and can break soundness if improperly referenced.

[PLeVasseur]

1. Prefer Explicit, Intent-Revealing Type Definitions

Rule: Use type aliases or newtypes (tuple structs) when they increase clarity or strengthen type safety.

Use a newtype when two quantities have the same underlying primitive but different semantics:

struct Meters(u32);
struct Seconds(u32);

Use a type alias when the semantic meaning is exactly the same as the underlying type:

type UserId = u64;

Rationale: Prevents accidental mixing of logically distinct values, improves safety, and assists API discovery.

Feels like this could be two rules -- one for when to use type aliases and one for when to use newtypes.

2. Avoid Using impl Trait in Public Signatures (Except for Return Types)

Rule: In public APIs, do not use impl Trait in argument position; prefer explicit trait bounds.

Allowed (return position):

pub fn iter_names() -> impl Iterator<Item = String>;

Avoid in parameters:

// Less clear
pub fn process(x: impl Read) { ... }

// Preferred
pub fn process<R: Read>(x: R) { ... }

Rationale: Makes type relationships explicit and helps prevent breaking API changes.

I think more rationale around why to avoid impl Trait in function parameter position would be good, especially regarding prevention of breaking API changes.

I asked a robot why and it gave some nice reasoning that could be included in a full write-up for rationale.

3. Use Traits to Represent Capabilities, Not Categories

Rule: A trait should describe behavior, not a “type group.”

Bad example:

trait Vehicle {} // no behavior

Good example:

trait Drivable {
    fn drive(&mut self, km: u32);
}

Rationale: Traits are for polymorphism and abstraction of behavior, not tagging or inheritance.

I'm not sure that I agree with this one. I've seen empty traits used to enforce invariants.

I asked a robot and it gave some examples of where empty traits can come in handy and how this rule might be refined.

---

Gonna come back to think about the rest later.

[felix91gr]

1. Prefer Explicit, Intent-Revealing Type Definitions

Absolutely. This helps a lot. It's a good rule.

My only nitpick, but this is more of a nit with the universe and not the rule, is that I don't think there's a reasonable way to check for this with Static Analysis. It would have to be... well, Undecidable, of course. But also... Manual-Only? Something like that. Or perhaps it would need to be a Principle, and not a Rule.

Anyway, I don't know how to make this a properly actionable rule. That's what bothers me.

But yeah, I love it. This is a great principle that Rust allows for.

EDIT: @PLeVasseur said

Feels like this could be two rules -- one for when to use type aliases and one for when to use newtypes.

And I think I agree. It's best to be as atomic as possible when mandating something, I think.

[felix91gr]

3. Use Traits to Represent Capabilities, Not Categories

Rule: A trait should describe behavior, not a “type group.”

Bad example:

trait Vehicle {} // no behavior

Good example:

trait Drivable {
    fn drive(&mut self, km: u32);
}

Rationale: Traits are for polymorphism and abstraction of behavior, not tagging or inheritance.

Inheritance, which I agree is undesirable, is basically impossible to do in Rust without contorting oneself significantly. So I don't think we need to worry about that one.

But Tagging is actually very useful. The two traits from stdlib that first come to mind are Send and Sync, but I'm pretty sure there are many others. I've seen traits used in this way all throughout the ecosystem, and the reasoning for using them that way tends to be sound. I think that's what @PLeVasseur was referring to when he addressed this one.

4. Keep Traits Small and Focused

Rule: Prefer small cohesive traits (“single responsibility”). Avoid large, multipurpose trait collections.

Good:

trait Serialize { fn serialize(&self) -> String; }
trait Deserialize: Sized { fn deserialize(s: &str) -> Self; }

Avoid:

trait SerdeLike {
    fn serialize(&self) -> String;
    fn deserialize(s: &str) -> Self;
    fn version(&self) -> u32;
    ...
}

Rationale: Allows flexible composition, easier mocking, and fewer breaking changes.

I don't know about this. I mean, I sort of get what you're going for, but it feels to me more like a Principle (like Rule 1 quoted on a comment I made earlier). It doesn't feel actionable or enforceable, if that makes sense. I don't think this is something we can put in some Static Analysis tool in an effective way.

One could imagine an analysis asking for traits to not have more than e.g. 3 functions, but that would miss the point of the Rule. Some Traits with 3 functions are already not cohesive, and some Traits with 6 functions make complete cohesive sense as they are.

6. Prefer #[derive] for Simple Traits

Rule: Where correct, use deriving for traits such as:

Copy, Clone

Debug

PartialEq, Eq

PartialOrd, Ord

Hash

Default

Example:

#[derive(Debug, Clone, PartialEq, Eq)]
struct Point { x: i32, y: i32 }

Rationale: Derivations are consistent, tested, and faster to maintain.

This one (or something very close to it) seems like an absolute easy win. The derive system for such traits is completely correct and if you asked around, I'm pretty sure 99.8% of people would agree with the rule.

I would use a different wording perhaps:

• What constitutes a "Simple Trait"? I think there's a better term for what we mean here, and I would explain what kinds of traits should be implemented in this way.
• And I would change it from "Where correct, " to "Where trivial, ". Because we can guarantee that the derive system gives correct implementations when the user doesn't need to manually implement the Trait in question for anything. When a type they are using needs a custom implementation, this guarantee starts to lie in their own hands - they are the implementer.

Otherwise, I agree 100%.

I should also mention that this would be enforceable. At least if the list of Traits that we want to be implemented in this way is already known, it can be used as the configuration parameter for a Clippy lint that checked for this rule without false positives or false negatives (ie it would be decidable as well, as far as I'm aware).

There might be a lint already for this, but I'm not sure. If there is, it just goes to show how universal this rule is :)

[felix91gr]

12. Use From/Into for Conversions, Not Ad Hoc Methods

Rule: Use standard conversion traits instead of custom to_xxx() or from_xxx() names.

Example:

impl From<u32> for Duration {
    fn from(secs: u32) -> Self { Duration::from_secs(secs as u64) }
}

Rationale: This leverages the universal conversion ecosystem.

I agree with this rule. I would add:

• A bit more context to the rationale (maybe examples of how this is used in core), and
• The fallible conversion traits as well (TryInto, TryFrom).

I wonder how enforceable this is. I worry that the best analysis possible for this would have to be heuristic: there is no way, not that I can think of right now, to know for certain that a specific method is being written with the intention of being a converter method. We could definitely lint for all the methods that do to_bleh(...) -> Bleh and such, but this criterion would definitely be incomplete.

Dunno. Lemme know what you think.

15. Prefer Safer Type Representations (Avoid unsafe Struct Layout Unless Necessary)

Rule: Avoid repr(C) or repr(packed) unless absolutely required for FFI or specific memory layout.

Packed structs remove alignment guarantees and can break soundness if improperly referenced.

Making unaligned references, like for example to unaligned fields of packed structs, is Undefined Behavior. However, creating such references is no longer possible in Safe Rust. So I think that part should perhaps be developed under the Unsafe chapter?

Regarding repr(C), I think I agree. I mean, what you wrote is precisely its use-cases:

• Crossing the FFI boundary and
• Enforcing a specific memory layout.

I guess it merits being repeated in the rule itself.

Though like a few of the aforementioned rules, this one would resemble a Principle a lot more than a Rule. I don't think there's any way to enforce this as a Rule.

Well, perhaps we can lint for any uses of repr(C) and ask the user to justify it using allow(reason: "I need this for FFI"). Might be a bit noisy, but... well, we can see how it goes.