This is the emerging schema and test-cases we're using for code examples:
Code Example Schema (Template)
- Applies To
- Solution Example
- Problem Example
- Test Case
- Expected Results
- More Information
- Additional Resources
Code Example Schema (Template explained and test cases)
Insert title that resonates from a findability perspective.
- Does the title distinguish it from related examples?
- If technology is in the title, is the version included?
Insert 1-2 lines max description of the intent.
- Does the description crisply summarize the solution
- Is the intent of the code clear?
Insert the key technologies/platform the code applies to.
- Versions are clear?
Insert bulleted list of task-based outcomes for the code.
- Is it clear why the solution example is preferred over the problem example?
Insert code example as a blob within a function. The blob allows quick reading of the code. It also allows quickly testing from a function, inlining within other code, or refactoring for a given context. The alternative is to factor up front, but this increases complexity and can negatively impact consumption. This leaves refactoring to the developer for their given scenario.
- Is the code example organized as a blob within a function that can easily be tested or refactored?
- Do the comments add insights around decisions?
- Are the comments concise enough so they don't break the code flow?
List examples of common mistakes along with issues.
- Are the mistakes clear?
- Are the patterns and variations of the problems clear?
Insert relevant setup information. Write the code to call the functional blob from Solution Example.
- Is setup Information included?
- Does the example call the functional blob in the Solution example?
Insert what you expect to see when running the test case.
- If you run the Test Case, do the Expected Results match?
Insert bulleted list of key usage scenarios.
- Usage scenarios are a flat list?
- Usage scenarios are based on real-world?
- Usage scenarios convey when to use the code?
Optional. Insert more information as necessary. This could be background information or interesting additional details.
Optional. Insert bulleted list of descriptive links to resources that have direct value or relevancy.
- The links starts with the pattern "For more information on X, see ..."?
- The links are directly relevant versus simply nice to have?
We're using this schema for our Security Code Examples Project.