Skip to content

Example code guidelines #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ehuss opened this issue Feb 29, 2024 · 0 comments
Open

Example code guidelines #19

ehuss opened this issue Feb 29, 2024 · 0 comments
Labels
C-meta-formatting Category: Meta discussions about how content should be formatted in raw markdown

Comments

@ehuss
Copy link
Contributor

ehuss commented Feb 29, 2024

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?
@ehuss ehuss mentioned this issue Mar 8, 2024
@JoelMarcey JoelMarcey added the C-meta-formatting Category: Meta discussions about how content should be formatted in raw markdown label Mar 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-meta-formatting Category: Meta discussions about how content should be formatted in raw markdown
Development

No branches or pull requests

2 participants