Examples are not Documentation (nereux.blog)
from Nereuxofficial@programming.dev to rust@programming.dev on 03 May 2024 22:35
https://programming.dev/post/13611525

#rust

threaded - newest

sugar_in_your_tea@sh.itjust.works on 03 May 2024 22:42 next collapse

The only thing worse than a bad example is documentation like this:

fn do_thing(…)

Does thing.

It adds nothing, other than letting you know they were there and decided not to actually provide something useful.

Nereuxofficial@programming.dev on 04 May 2024 08:47 collapse

Yeah that just wastes both people’s time

Deebster@programming.dev on 04 May 2024 01:26 next collapse

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!

Nereuxofficial@programming.dev on 04 May 2024 08:45 next collapse

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

noddy@beehaw.org on 04 May 2024 08:55 next collapse

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.

crispy_kilt@feddit.de on 08 May 2024 11:40 collapse

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.

BB_C@programming.dev on 04 May 2024 02:25 next collapse

Examples ARE usage documentation.

What value is this blog supposed to be adding exactly?
The fact that top-level and API descriptive explanations are important?
The fact that some projects don’t have complete documentation?
To whom exactly would this be considered new information?

pkill@programming.dev on 04 May 2024 10:01 collapse

This. I can’t count HOW MANY FUCKING TIMES I had to either look up the source code or search GitHub for code using a function from a given library because the documentation was so laconic and/or disjointed.

anlumo@feddit.de on 04 May 2024 09:01 next collapse

clap and bevy are big offenders there. It’s really hard to learn how to use them due to this.

tatterdemalion@programming.dev on 04 May 2024 21:23 next collapse

Are you kidding me? Clap has some of the best documentation of any crate.

anlumo@feddit.de on 06 May 2024 12:38 collapse

I just checked again, and apparently they finally added some documentation since I last checked. The section about the macro stuff just used to say “look at the examples”.

tatterdemalion@programming.dev on 06 May 2024 14:21 collapse

Ah that explains it.

SatouKazuma@lemmy.world on 13 May 2024 11:25 collapse

It sucks that there aren’t (in my limited experience) a ton of engines out there with good documentation (at least that are built in Rust). I’ve started trying to build my own engine, but the complexity and time required are certainly a bit of a barrier, especially for the game I’m working on. (N.B. - The game is nowhere close to being in any sort of state to be shown, so please don’t ask 😆)

anlumo@feddit.de on 13 May 2024 14:26 collapse

My experience has been that good documentation is mostly something done if somebody gets paid for the work. People working on stuff in their spare time just don’t care enough to document their project.

SatouKazuma@lemmy.world on 13 May 2024 18:44 collapse

That, or they don’t care enough to pick it back up if they ever drop it. Nothing hurts worse than forgetting what you’re trying to do because you don’t even comment your code.

crispy_kilt@feddit.de on 08 May 2024 11:38 collapse

Uhm. Yes they are.