I'd like to save code pieces I write for testing libraries, or ideas, or for documentation. This code is going to be linked in ADRs, or commit messages, or in task tracker. It's not directly related to the project, it's only illustrative.
So, the question is: where to put this code? I could use the examples/ folder, but it's unclear if it is reserved for examples on how to use a library, when I publish one.
I could create a single crate for these pieces of code, I could create multiple crates, I could create a doc/examples/ directory and do cargo new in it for every code piece. I also could use rust-script to have self-contained single source files.
What option would an experienced rust developer choose?
I understand this is probably bikeshedding, but I'd like to maintain order in my project.
Except putting these snippets in examples/, which is where Cargo auto-discovers examples—binaries that illustrate how to use the public API of your library—, all suggestions sound fine to me. I personally would probably prefer a doc/snippets/ or doc/examples/ directory with simple *.rs files or a whole Cargo package, if the snippets are supposed to be executable. Gists or even better Playground links (if your snippets compiles there) would also be an acceptable place to put them IMO.
It's not reserved per se, but inside a Cargo package, the examples/ directory will be used by Cargo to automatically discover examples. Examples should be (my emphasis):
Files located under the examples directory are example uses of the functionality provided by the library.
You can disable auto-discovery by setting the package.autoexamples key in your Cargo.toml to false, if you want to use the examples/ directory for something else. However, I'd argue that it is not a good idea, not because of the technicalities of Cargo's target discovery, but because it will confuse your users. I regularly browse the examples/ in a project to understand how to use a library. I'd be very confused if I find some snippet unrelated to the package there.
For more info on package layout and Cargo targets, see:
I have a folder named "amb" ("ambitions") where I put various code fragments or even whole packages that did not make it into the production code, but I may return to them in the future. It is clear what it is, and it is much better than having commented-out sections in production code. It actually doesn't happen very often that I need something from there, but it has happened a few times. If this is my own project, I usually also commit it to benefit from git as from backup. If I work in the team, I add it to .gitignore.
If the code has been in production and then removed, it stays in the commit history. However, there may be code that has never been committed, or at least not to the main branch, so it may be hard to find later.
It is worth thinking a litter if the code fragment is really useless. Some make great as examples, test cases or (if simple) code sections in documentation comments.