Establish recipe style guide

[aturon]

We need to firm up a consistent style for all of the examples to follow.

[aturon]

I've got a stub document here that we can use for collaborating.

[budziq]

I find myself slightly daunted when trying to put my thoughts into a well structured form like in the dropbox paper. So I'll try to make some (possibly incremental) braindumps here and we will se where we get from there. So here we go :)

What makes a good cookbook entry?

This is highly subjective but for me the key qualities would be:

Code samples

• should compile without warnings (and ideally without clippy lints)
• should be formatted with rustfmt
• self contained. all the code required to achieve the desired effect (described in the title) should be contained within the code snippets. It should be ready to cut-n-paste into reader's code
• Idiomatic/rustic code (again subjective).
• avoid unwrap / expect or any other form of panicking unless it's established as best practice in given setting (assertions, build scripts)
• should employ consistent error handling strategies.
• A code that can be used to learn good practices (both in terms of performance and ergonomy)
• consistent with other examples
• relatively short fractal drawing example seams to be pushing the pain threshold
• parts of the snippet that are not essential to conveying the point of the example (error boilerplate, helper functions) should be hidden by default.
• examples should refrain from depending on external state, unless interfacing with the external world is part of the example (networking, databases, filesystem, etc.).
• if example depend on external state, then the code snippets should be marked no_run
• should avoid inline comments if possible (code and textual description should be enough)

Textual description

• title should be short and describe the problem at hand
• Correct wording, spelling and grammar
• concise, easy to understand and to the point
• most likely should avoid phrases like ("here we can see", "we can easily")
• consistent with other examples
• each example in given series should build on the previous. Starting with first example describing the basic details and further examples describing variations or added functionality (should it? how user is supposed to know about the previous more basic examples?)
• most likely it should avoid stating the obvious facts about the code (subjective)
• key points are mentioned and described
• key identifiers are mentioned and hyperlined to their docs.rs entries
• docs.rs entries ere hyperlinked with wildcard version specifiers
• if authoritative web based documentation on given subject exists, then it should be also hyperlinked

What is the standard form we expect?

In terms of text, I might not be a best judge but I remember that @dtolnay
had some opinions on the exact wording / language side of things #139. He might have some thoughts on this matter worth jotting down :)

In terms of the code, then one of the guideline to follow is our not on error handling.
Id say that a form of

• Descriptive title slug
• Short 1-4 sentence hyperlinked description
• single code snippet (ideally upto 50 lines collapsed and upto 100 lines expanded)
• possibly additional example output
• all extern crates (except for hidden boilerplate like error_chain) should be listed in example badges section

[AndyGauge]

So I believe there is a style guide that is established. It is here Contributing.

I propose adding to it, and breaking it into sections to make it digestible. I also think it is missing what should be in the 1-4 sentence description. The paragraph that describes comments switches narrative to the description, and fails to express what is desired from a contribution. When this paragraph was written, basic must have been in a different state, because today looking at basic for examples is overwhelming.

I propose a rewrite of the example guideline, but keep it as the style guide. I suggest removing the duplicated information, and organizing it into sections, with an embedded example. At the end of the breakdown with example, outline the desire to have examples use quality, approved crates.

As for details of what makes a quality example, I think @budziq did a great job outlining specifics, and I think they should be included in the Contributing.md file. I think we should remove subjective points, and simply include code standards. I think we should exclude calling out examples except for the embedded example.

I would love to hear feedback if inline comments should be removed or included. In surveying the comments that are currently included, I really see @budziq 's point about removing them.

I don't see it relevant to include spelling and grammar points, we can assume that contributions should know this. Instead of 'avoid using phrases' I suggest we recommend 'using 3rd person narrative to describe the execution path, including links to the crate's API documentation'.

TL;DR
use Contributing as style guide, but include an example and break it into sections.