Rustacean

Readable Generic APIs

3 min read

Readable Generic APIs

Designing generics that read well: accept impl Trait for inputs, return concrete or impl Trait, keep bounds minimal and named via where.

What it is

A readable generic API gives callers flexibility without forcing them to decode unnecessary type parameters. The signature should show the behavior required, not every incidental implementation detail.

Rust gives several tools for this: named type parameters, impl Trait arguments, return-position impl Trait, trait bounds, and where clauses.

Good generic design is part syntax and part restraint. Every bound is a requirement callers must satisfy and maintain.

How it works

arg: impl Trait is syntax sugar for an anonymous generic parameter. It is concise when each argument can be any type implementing that trait. Named generics such as fn same<T: Trait>(a: T, b: T) are needed when two positions must have the same concrete type.

Return-position impl Trait hides the concrete return type from callers while preserving static dispatch. The function body must still return one concrete type, even if control flow has branches.

where clauses move complex bounds after the signature so the function name, parameters, and return type remain readable.

Example

use std::fmt::Display;
 
fn join_display(values: impl IntoIterator<Item = impl Display>, sep: &str) -> String {
    values
        .into_iter()
        .map(|value| value.to_string())
        .collect::<Vec<_>>()
        .join(sep)
}
 
fn main() {
    assert_eq!(join_display([1, 2, 3], ", "), "1, 2, 3");
}

The API accepts any iterable of displayable items without exposing a named generic parameter that callers do not need to know.

Edge cases

Use named generics when relationships between arguments matter:

use std::fmt::Debug;
 
fn assert_same<T>(left: T, right: T)
where
    T: PartialEq + Debug,
{
    assert_eq!(left, right);
}
 
fn main() {
    assert_same(3u8, 3u8);
}

fn assert_same(left: impl PartialEq + Debug, right: impl PartialEq + Debug) would allow different concrete types and would not express the same contract.

Common errors

Returning different concrete types behind impl Trait fails:

use std::fmt::Display;
 
fn label(flag: bool) -> impl Display {
    if flag {
        "ready"
    } else {
        // 0
        "0"
    }
}

If the else branch returned 0, the diagnostic would be:

error[E0308]: `if` and `else` have incompatible types

Fix by returning one concrete type, an enum, or a trait object when dynamic dispatch is intended.

Best practice

  • ✅ Use impl Trait for simple input positions with no need to name the type.
  • ✅ Use named type parameters when multiple arguments or return values must share a type.
  • ✅ Prefer where clauses once bounds distract from the function shape.
  • ✅ Keep bounds minimal: require Display if you only format, not Debug + Clone + Display.
  • ✅ Return concrete types unless hiding a long iterator/closure type materially improves the API.

Pitfalls

  • ⚠️ Do not expose generic parameters just because an implementation is generic internally.
  • ⚠️ Do not add Clone to avoid thinking about Ownership; prefer borrowing when possible.
  • ⚠️ Do not return impl Trait from branches with different concrete types.
  • ⚠️ Overly broad bounds create unnecessary compile errors for callers.
  • ⚠️ Trait objects (dyn Trait) and impl Trait solve different problems; choose deliberately.

See also

Type Inference · Functions · The Display Trait · The Debug Trait · PartialEq · Iterator Method Trio · Ownership · Borrowing · Basic Concepts & Syntax

Sources

Graph View

Backlinks