44
Examples are not Documentation
(nereux.blog)
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
this post was submitted on 03 May 2024
44 points (81.4% liked)
Rust
6055 readers
162 users here now
Welcome to the Rust community! This is a place to discuss about the Rust programming language.
Wormhole
Credits
- The icon is a modified version of the official rust logo (changing the colors to a gradient and black background)
founded 1 year ago
MODERATORS
My absolute favourite is when the examples say something like "production code should not be written like this, this is just for clarity" with no indication of what's wrong with the code.
Is it just normal Rust stuff like there's unwraps everywhere and it's one big file? Does the example have security or performance problems? Is the example unidiomatic or over-verbose or is it ignoring features real-world code would use? EXPLAIN YOURSELF!
Yeah that's the fun part!
Maybe there are also some security implications of the code?
Because the thing is: That code is probably gonna end up in production somewhere
I personally prefer the straight forward everything in one file examples. The worst examples are those that come with its own ad hoc example framework I first need to understand before I can understand the example.
It's probably to encourage people to underdtsnd the example properly then write their own code. Too many people copy/paste examples without understanding them completely.