I really like the level of that documentation. Very beginner friendly, with a reasonable level of completeness mingled within. A short diversion for basic std::env::args() access, with a quick switch to using clap for decent common behaviour.
Having worked on a project written in nim today the contrast is huge: The documentation isn't great, the stdlib argument parsing is odd, if you use argparse¹ then nim-using devs expect different behaviour, etc.
For anyone who hasn't seen it, I highly recommend structopt over clap. It is a wrapper around clap which provides type safe parsing of CLI arguments into a struct you define. It is also what TFA uses.
As an Australian, no, not at all, but many people are certainly quite sensitive about such things and we generally have to acknowledge/modify behaviour as decent internet citizens because of it.
Here’s another fancy idea: Write that README before you write the code.
I find this idea to be very effective, as long as the scope can be kept to a minimum (think MVP). I've seen it work not only for CLI apps, but also for simple HTTP API servers.
I find it to be a great method of development. The core use case (what the project is and why it exists), and the public interface are so important, and often overlooked when people start a project by writing the code first. I tend to write the README in my head naturally, before I start a project, so writing it down makes sense.
I also like to write the developer guide part of the README at the beginning (how to setup a development environment), so I ensure the project is easy to contribute to.
If you're working on a command line application, I would also suggest writing the manual page before you start writing the code. You can always change it later, but knowing the surface area of the tool, such as the subcommands and arguments, gives you a good idea of what you're looking to implement.
I'm working on a Rust CLI boilerplate/starter template. You can see the code here: https://github.com/omarabid/rust-starter . It's pretty much ready for consumption beside the Readme, documentation and cleaning/re-organizing some parts of the code.
The idea is to have all of this tutorial (and more) in a blank template so that you can get started on your CLI very fast and focus on doing the logic rather than making choices. (Rust-Starter is biased, it picks the crates and you just make use of the structure).
If you are interested, feel free to look at the code, open an issue, or send me an email!
Hi, author of large parts of this here! This was written in the lead up to the Rust 2018 edition release last year, but it should still be pretty much up-to-date.
There is a lot of more info and discussions on the associated repo [1]. We didn't have a lot of time to quickly respond to everything recently, but: Questions, typo fixes, and additional chapters are very welcome :)
17 comments
[ 3.1 ms ] story [ 45.0 ms ] threadHaving worked on a project written in nim today the contrast is huge: The documentation isn't great, the stdlib argument parsing is odd, if you use argparse¹ then nim-using devs expect different behaviour, etc.
1. https://github.com/iffy/nim-argparse
It's: The Fucking Article
https://clap.rs/2019/03/08/clap-v3-update-structopt/
I find this idea to be very effective, as long as the scope can be kept to a minimum (think MVP). I've seen it work not only for CLI apps, but also for simple HTTP API servers.
I find it to be a great method of development. The core use case (what the project is and why it exists), and the public interface are so important, and often overlooked when people start a project by writing the code first. I tend to write the README in my head naturally, before I start a project, so writing it down makes sense.
I also like to write the developer guide part of the README at the beginning (how to setup a development environment), so I ensure the project is easy to contribute to.
The idea is to have all of this tutorial (and more) in a blank template so that you can get started on your CLI very fast and focus on doing the logic rather than making choices. (Rust-Starter is biased, it picks the crates and you just make use of the structure).
If you are interested, feel free to look at the code, open an issue, or send me an email!
There is a lot of more info and discussions on the associated repo [1]. We didn't have a lot of time to quickly respond to everything recently, but: Questions, typo fixes, and additional chapters are very welcome :)
[1]: https://github.com/rust-lang-nursery/cli-wg