Example code guidelines

[ehuss]

The following are some questions about including code samples in the text.
See https://github.com/rust-lang/reference/blob/master/STYLE.md#code-examples for the reference guide.

• Will there be illustrative examples in the spec?
  • ehuss's preference: Yes, I think illustrations are very helpful.
  • Consider that some readers will skip or skim the text and look at the code first.
• How often should there be examples? Are there any guidelines for when they should and should not be used?
• If we have a separate testsuite, can some of those examples be offloaded to the testsuite?
  That is, instead of showing some examples inline, just allow the user to somehow view the testsuite for a specific rule.
• Should there be naming conventions, such as avoiding nonsense terms like foo/bar/baz, and using realistic terms instead.
  • ehuss's preference: I would encourage not using nonsense terms, and try to use names that are illustrative of the concept whenever possible (example).
• Should the examples prefer to be realistic of what a user would actually write?
  That can be difficult, since that often requires longer examples. Unrealistic or trivial examples can be confusing.
• Are there guidelines for balancing length versus clarity? There are times when to illustrate some concept, it may require a significant amount of code. At what point is too much? mdBook supports hiding irrelevant portions of code, but that has limitations.
• Should example code be inline within the text, or outline (like TRPL) and use includes? Inline is easier to author, outline is easier to test.
• If using rustdoc (mdbook test) to test, then there should be guidelines on using tags like no_run, ignore, E errors, etc.
• Should inline code samples be tested with mdbook test, or via a separate test infrastructure?
  mdbook test is very easy to use, and makes it easy to see the code in the source text. However, it is very limited in its capabilities.
  • ehuss's preference: I think we should (eventually) invest in a test infrastructure using compiletest or ui_test. We can perhaps have some kind of hybrid inline/outline model, but I don't know what that might look like.
• Should examples be formatted with rustfmt?
  • Any non-default options?