Should code examples be self-contained?

[rcseacord]

What should our code examples look like?

Should the code be copy-pastable so it will compile?
If that's the case, having at a minimum a main() { /* ... */ } visible in every example is helpful or we should communicate somehow that it may be needed when people are copy-pasting snippets.

Or maybe code snippets should be in self contained functions that won't build without a main?

[felix91gr]

Reference for a nice way to do this (we discussed this in core meeting in 16-12-2025): https://lukaswirth.dev/tlborm/decl-macros/patterns/tt-muncher.html

How it looks at a glance:

After clicking the "Play" button to run the code:

And after clicking the "Eye" button to show the hidden main function (because it's not the main focus of the code block):

[felix91gr]

We should also run rustfmt on the examples before we render them, or perhaps before we merge them?

The current formatting is all over the place.

[rcseacord]

For the formatting thing, it's a little annoying that we have to add a minimum of nine spaces before every line of Rust code to use it in the restructured text file.

[felix91gr]

Code examples with the unsafe keyword should probably also be run with Miri.

I wonder if there's a way to tell the runner either:

• "Hey, this code shouldn't have UB in its execution", or
• "Hey, this code should have UB in its execution"

Having those options available would allow us to test that our code examples either have or don't have, Undefined Behavior.

(For most cases that will be the Compliant Example(s) and the Non-Compliant Example(s), respectively)

[rcseacord]

Not all noncompliant code examples need undefined behavior, of course. Compliant examples definitely shouldn't have any.
I think now it becomes tricky to automate. The noncompliant text can say something like this code has UB, or the behavior is undefined. Finding UB in compliant solutions should be easier.

[rcseacord]

For the CERT standards we would try to ensure that compliant examples complied with all the other rules. To automate, this might involve running all the linters.

Ideally, noncompliant examples would only break the rule they are examples for and no other rules. When they broke other rules, we would call this out.

[PLeVasseur]

This was addressed by:

• Address code examples features: copyable, runnable, hideable + add miri #344
• fix: loosen parsing logic for options in code examples and warn on fix #345

Take a look at the currently deployed version, e.g. this one:
https://coding-guidelines.arewesafetycriticalyet.org/coding-guidelines/expressions/index.html#compl_ex_uilHTIOgxD37

That should give a sense of what's possible.

I'm going to close this as completed for now.

Please open more issues with other ideas to improve.