Rust – Andy Balaam's Blog

Rust 101 – 19: Creating a nice API

Tips and rules for writing good APIs that are easy for other people to use. Try to make them Unsurprising, Flexible, and Obvious.

Series: 1: Intro, 2: Language basics, 3: Memory and ownership, 4: Exercises A1, 5: References, 6: Structs and Enums, 7: Panic and Result, 8: Methods, 9: Vec and Box, 10: Strings, 11: Exercises A2, 12: Traits, 13: Type Params, 14: std Traits, 15: Lifetimes, 16: Exercises A3pt1, 17: Exercises A3pt2, 18: Dependencies, 19: API design

Links:

Slides: Rust 101 – module B
Exercises: Exercises for Rust 101 module B

The course materials for this series are developed by tweede golf. You can find more information at github.com/tweedegolf/101-rs and you can sponsor the work at github.com/sponsors/tweedegolf. They are released under the Creative Commons Attribution Share Alike 4.0 International license.

Rust 101 – 18: Dependencies and Cargo.toml

How to describe details of your Rust project with a Cargo.toml file, and how to find and add dependencies (other people’s code).

Links:

Slides: Rust 101 – module B
Exercises: Exercises for Rust 101 module B

Rust 101 – 17: Exercises for module A3 (part 2)

Finishing off the exercises on Rust traits, designing a customised version of Vec.

Links:

Slides: Rust 101 – module A3
Exercises: 101-rs.tweede.golf/A3-traits-generics/mod.html

Rust 101 – 16: Exercises for module A3 (part 1)

Going through some exercises on Rust traits, designing a customised version of Vec.

Links:

Slides: Rust 101 – module A3
Exercises: 101-rs.tweede.golf/A3-traits-generics/mod.html

One import per line is best

Rust has a feature where if you import two things from the same module you can abbreviate it like this:

use mypkg::{MyStruct1, MyStruct2};

If you prefer, you can keep them separate, like this:

use mypkg::MyStruct1;
use mypkg::MyStruct2;

I do prefer. Strongly.

Advantages of the abbreviated style

Fewer lines of code
Fewer characters of code

Advantages of the separated style

Simpler diffs with fewer conflicts. If I add or delete an import, it adds or removes exactly one line. This makes it easier to read diffs and reduces conflicts when merging.
Less diff noise when lines overflow. Adding or removing an import is less likely to cause the code formatter to reflow the line. Reflows make it hard to see which dependencies have changed when reading a diff.
Easier searching. If I’m trying to find out where a particular type is used I can search for its full path, and my search will find all the places I import it.

Easier to read. I find line of code like this really hard to read:

use crate::{
    gossiping::{GossipRequest, GossippedSecret, SecretInfo},
    identities::{ReadOnlyDevice, ReadOnlyUserIdentities},
    olm::{OutboundGroupSession, PrivateCrossSigningIdentity},
    types::events::room_key_withheld::RoomKeyWithheldEvent,
    TrackedUser,
};

I think the separated style is much better, and I wish Rustfmt defaulted to using it. What do you think?

rustfmt config

To enforce my preferred style, include this in your rustfmt.toml:

imports_granularity = Item

(Rustfmt docs)