Expand guidelines for examples

[ehuss]

I'd like to extend the examples guidelines to provide better guidance on writing examples.

• How often should there be examples? Are there any guidelines for when they should and should not be used?
• 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.
  • How much should we rely on outline examples or tests (for example, the links to the testsuite)?
• Should examples be formatted with rustfmt?
  • Any non-default options?

References:

• Google code samples