Advanced Rust API Design: Unsurprising Naming Principles and Common Traits

Designing robust APIs in Rust requires adhering to the unsurprising principle, also referred to as the least-surprise principle. This concept dictates that the interfaces you build should be completely intuitive, allowing users to accurately guess functionality simply by looking at the code without needing to relearn concepts. For instance, encountering an interface name that includes error immediately signals its role in error handling.

Achieving this level of predictability demands careful attention to specific guidelines. Interface names must strictly follow established conventions commonly found within the Rust standard library and its broader community. Furthermore, components sharing identical names must behave identically to prevent users from accidentally writing flawed code.

Stock photo for illustration only, not from the actual event

Beyond naming conventions, developers should proactively implement most standard traits even when immediate use is not required. Because the orphan rule prevents users from implementing foreign traits for foreign types on their own, pre-implementing these standard traits ensures your custom types satisfy common user expectations seamlessly.

A prime example is the Debug trait, which is recommended for almost all types and is most efficiently implemented using #[derive(Debug)]. Additionally, while most types default to being Unpin, self-referential types require markers like std::marker::PhantomPinned to remain !Unpin and prevent internal pointer invalidation during movement. If your type lacks any of these traits, it is strongly recommended to document that limitation clearly.

Source: Dev.to