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?
References:
I'd like to extend the examples guidelines to provide better guidance on writing examples.
That can be difficult, since that often requires longer examples. Unrealistic or trivial examples can be confusing.
References: