Rust Coding Guidelines (Chinese Edition)

The Rust standard library provides numerous built-in traits. To ensure code correctness, performance, and idiomatic design, follow the specific guidelines provided for each trait implementation or usage. These guidelines cover common pitfalls in implementing traits like Borrow, Default, Copy, Clone, From, Into, Hash, Ord, and Deref.

Available guidelines include:

- **Borrow**: Ensure consistency when implementing `Borrow`.
- **Default**: Use specific type `default()` instead of `Default::default()`; prefer `#[derive(Default)]` over manual implementation.
- **Copy/Clone**: Do not implement `Copy` for iterators; do not call `std::mem::drop` or `std::mem::forgot` on `Copy` or reference types; use `.copied()` instead of `.cloned()` for `Copy` types; avoid manual `Clone` for `Copy` types.
- **Hash/Ord**: Avoid manual `PartialEq` when using `#[derive(Hash)]`; avoid manual `PartialOrd` when using `#[derive(Ord)]`.
- **From/Into**: Implement `From` instead of `Into`.
- **Deref**: Do not use `Deref` to simulate inheritance.

When designing APIs that perform I/O operations using raw handles (such as file descriptors), be aware that using the AsRawFd trait can be unsafe. Because AsRawFd::as_raw_fd returns a raw integer (RawFd) without restrictions, an end-user can pass any arbitrary integer to your function. This can lead to:

1. Accessing incorrect resources: Users can pass valid but unintended file descriptors (e.g., do_some_io(&7)).
2. Breaking encapsulation: Users can create aliases for private handles, leading to "Action at a distance" (where behavior in one part of the program is unexpectedly affected by distant, hard-to-trace code).
3. Memory safety violations: In certain edge cases, violating I/O safety can directly lead to memory safety issues.

To prevent this, avoid accepting AsRawFd if you need to guarantee that the I/O is performed only on a specific, controlled resource. Instead, consider accepting types that own the resource or use higher-level abstractions that enforce ownership and lifetime rules.

// Example of an unsafe API pattern that allows arbitrary I/O
pub fn do_some_io<FD: AsRawFd>(input: &FD) -> io::Result<()> {
    some_syscall(input.as_raw_fd())
}

// This allows dangerous calls like:
// do_some_io(&7) 

In Rust, comments are categorized into two types: regular comments and documentation comments. When following these guidelines, note that the term "comments" refers to both types, while the term "documentation" specifically refers to documentation comments.

Regular Comments

Used for internal notes that are not intended to be part of the public API documentation. Use:

• // (Line comment)
• /* ... */ (Block comment)

Documentation Comments

Used to generate documentation via rustdoc. These are visible to users of your API.

• /// (Outer documentation comment: used to document the item following the comment, such as a function or struct).
• //! (Inner documentation comment: used to document the item containing the comment, such as a module or a crate).
• /** ... **/ (Block documentation comment).

// This is a regular line comment
/* This is a regular block comment */

/// This is an outer documentation comment for the following function
fn my_function() {}

//! This is an inner documentation comment for the current module

The Deref trait is specifically intended for implementing custom pointer types (e.g., smart pointers like Box or String). While implementing Deref can create behavior similar to inheritance (allowing a wrapper type to access methods of an inner type), this is strongly discouraged in Rust.

Rust emphasizes explicit conversions. Deref is one of the few sources of implicit behavior in the language. Overusing it increases the amount of implicit coercion in your codebase, which can lead to subtle bugs and make code harder to reason about.

// BAD PRACTICE: Using Deref to simulate inheritance
use std::ops::Deref;

struct Foo {}

impl Foo {
    fn m(&self) {
        // ...
    }
}

struct Bar {
    f: Foo
}

impl Deref for Bar {
    type Target = Foo;

    fn deref(&self) -> &Foo {
        &self.f
    }
}

fn main() {
    let bar = Bar { f: Foo {} };
    // This call is implicit via Deref coercion, which is discouraged for inheritance simulation
    bar.m();
}