Rust Async Best Practices: Tokio Runtime, Channels & Concurrency Guidelines

## Core Principles
**Do:** Craft readable, modular Rust code using snake_case for functions/variables and PascalCase for types, with descriptive names like `data_ready`.
*Example:*
```rust
async fn process_data(data_ready: bool) -> Result<(), Box<dyn std::error::Error>> {
    // Clear logic here
}
```
**Don't:** Repeat code or use vague names like `x` that hide intent.
*Example (Avoid):*
```rust
let x = true; // Unclear purpose
```

## Async Runtime Usage
**Do:** Rely on Tokio for async tasks, spawning with `tokio::spawn` and branching with `tokio::select!` for clean concurrency.
*Example:*
```rust
use tokio::select;
tokio::select! {
    result = some_async_op() => { /* handle */ },
    _ = tokio::time::sleep(Duration::from_secs(5)) => { /* timeout */ }
}
```
**Don't:** Mix sync blocking calls in async contexts; spawn blocking tasks separately.
*Example (Avoid):*
```rust
async fn bad() {
    std::thread::sleep(Duration::from_secs(1)); // Blocks runtime
}
```

## Channels & Shared State
**Do:** Opt for bounded `tokio::sync::mpsc` channels to enforce backpressure, and `Mutex`/`RwLock` for safe shared data.
*Example:*
```rust
let (tx, mut rx) = tokio::sync::mpsc::channel(100);
tokio::spawn(async move {
    tx.send(data).await.unwrap();
});
```
**Don't:** Use unbounded channels without limits, risking memory issues.
*Example (Avoid):*
```rust
let (tx, rx) = tokio::sync::mpsc::unbounded_channel(); // No backpressure
```

## Error Management
**Do:** Propagate errors with `?` and define custom types via `thiserror` for clarity.
*Example:*
```rust
use thiserror::Error;
#[derive(Error, Debug)]
enum AppError { #[error("IO failure")] Io(#[from] std::io::Error) }
async fn safe_op() -> Result<(), AppError> {
    let data = fs::read_to_string("file").await?;
    Ok(())
}
```
**Don't:** Ignore errors or use panics in production async code.

## Testing Async Code
**Do:** Employ `#[tokio::test]` and `tokio::time::pause` for deterministic tests.
*Example:*
```rust
#[tokio::test]
async fn test_timeout() {
    tokio::time::pause();
    tokio::time::advance(Duration::from_secs(1)).await;
    // Assert behavior
}
```
**Don't:** Rely on real sleeps in tests, causing flakiness.

## Performance Tips
**Do:** Yield with `tokio::task::yield_now().await` in loops and use `tokio::time::interval` for timers.
*Example:*
```rust
while condition {
    tokio::task::yield_now().await;
}
```
**Don't:** Perform CPU-heavy work in async fns; use `tokio::task::spawn_blocking`.

## App Structure
**Do:** Modularize into crates for networking/DB/logic, load configs via `dotenv`, and document with `///`.
**Don't:** Monolithically cram everything into `main.rs`.