Well written code examples

I have a soft question. (I've tried googling this, but not really had much luck - see below*)

I've recently started learning rust and I am now over some initial hurdles in understanding the language.

I'm at a point where I want to learn how to write good rust (I can scrap around and make things work, but I feel like I'm lacking in readability, generality and idiomatic style). To that end, I want to read code in projects that are considered exemplar examples of rust code, and hope to absorb idioms and style in the process!

Some criteria:

  1. The code doesn't need to achieve any grand outcome or even be particular useful - quality of the code and good 'rust style' is what I'm interested in.
    1a. But that said, some minimal level of real world application is required, I want to read projects where a real problem had to be dealt with, where someone thought about organizing their code and their thoughts. Toy examples are fine for learning syntax and basics, but it's very useful reading code where someone had to think a bit about why they did things the way they did.
  2. Ideally up-to-date projects from the past year or two, I'm acutely aware this language is evolving rapidly and would like to stay up-to-date.
  3. Ideally, but not strictly, no unsafe code ( good examples of how to handle/wrap unsafe sections are appreciated though ).
  4. No real requirements on the size of the project, but monstrous projects can sometimes be somewhat intractable (for a beginner anyway).
  5. Good style (This is after all the point of the question...)

Essentially, this is a question not about 'which crates are useful' (*which I think is done on a regular basis and is what Google likes to give me), but a question of 'Which crates are well designed?' and 'Which crates show off the programmer's understanding of idiomatic rust?'.

If you have any suggestions, I'd really appreciate examples of such projects and some short justification of why you consider it a really well written project that can be learned from!

1 Like

You should probably look at the core crates of the ecosystem. For example:

  • serde, because the core idea of separating data structures and serialization formats generically is very neat;
  • clap, because its #[derive(Parser)] is basically the right approach to strongly-typed argument parsing;
  • quote, because it demonstrates how to write usable, robust declarative macros for the real world.

I'd like to think that the code I write is also idiomatic; if I may nominate some of my own crates for studying, those would be:

  • parsel, which shows how to use types, composition, and derive macros, for avoiding boilerplate;
  • ring_api, which demonstrates the way I wrap a request-response protocol in a completely generic and extensible way.
4 Likes

Thanks! This is exactly the kind of reply I was hoping for.

The emphasis on the "why" is really really useful here! That's exactly the sort of information that a beginner like me needs to appreciate a design, and gives me something to pay attention to when reading.

(Anyone else reading, please copy this format and you'll have my eternal gratitude)

Next time you are looking up something in std's API docs, you should click the [source] button and have a read through the code behind it - it's probably one of the most well-documented large Rust codebases in the world.

You don't need to read the whole thing (I doubt any one person has), but it contains a lot of really well written code. The sys module is a bit gnarly because it has to deal with platform-specific awkwardness and unsafe code, so maybe steer clear of that.

The mini-redis project was also designed for the explicit purpose of teaching people how to use async code in the real world.

5 Likes

reqwest is a nice demonstration of error handling and reuse of types from other libs. I likely put axum in that bucket too. I would also study the collections’ use of iterators (std lib). The latter would be for two reasons: mostly how to leverage existing iterators for your own collection and to some degree for what you requested [1], see how traits and methods are used to leverage the relation between Vecs and slices (your everyday workhorses).


  1. arrays, slices and Vecs are unique, and the code is exceptional - good but rarely something you’ll do ↩︎

1 Like

That's actually pretty tough. Because some things in popular crates are made this way and not the other simply because of limitations which no longer exist.

Consider From vs Into dichotomy which confuses newbies immensely. Answer to why these two traits exist and is, actually, given in the documentation: prior to Rust 1.41, if the destination type was not part of the current crate then you couldn’t implement From directly.

But Rust 1.41 was released almost three years ago! You probably don't need to plan to workaround that problem when you write you own code!

Rather I recommend to start writing code and only look on popular crates to see if you can just reuse them to avoid reinventing the wheel, but if you actually decide to write your own code then just go and do that and look on code written by others when you couldn't solve some particular problem.

Writing working code in Rust is much easier than writing idiomatic code but refactoring is incredibly robust thanks to rigid, static typing thus it's often a good idea to separate these two steps.