Code Example Schema for Sharing Code Insights

  • Article

This is the emerging schema and test-cases we're using for code examples:

Code Example Schema (Template)

  • Title
  • Summary
  • Applies To
  • Objectives
  • Solution Example
  • Problem Example
  • Test Case
  • Expected Results
  • Scenarios 
  • More Information
  • Additional Resources

Code Example Schema (Template explained and test cases)

Title
Insert title that resonates from a findability perspective.

Test Cases:

  • Does the title distinguish it from related examples?
  • If technology is in the title, is the version included?

Summary 
Insert 1-2 lines max description of the intent.

Test Cases:

  • Does the description crisply summarize the solution
  • Is the intent of the code clear?

Applies To
Insert the key technologies/platform the code applies to.

Test Cases:

  • Versions are clear?

Objectives 
Insert bulleted list of task-based outcomes for the code.

Test Cases:

  • Is it clear why the solution example is preferred over the problem example?

Solution ExampleInsert 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.

Test Cases:

  • 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?

Problem Example
List examples of common mistakes along with issues.

Test Cases:

  • Are the mistakes clear?
  • Are the patterns and variations of the problems clear?

Test Case
Insert relevant setup information.  Write the code to call the functional blob from Solution Example.

Test Cases:

  • Is setup Information included?
  • Does the example call the functional blob in the Solution example?

Expected Results
Insert what you expect to see when running the test case.

Test Cases:

  • If you run the Test Case, do the Expected Results match?

ScenariosInsert bulleted list of key usage scenarios.

Test Cases:

  • Usage scenarios are a flat list?
  • Usage scenarios are based on real-world?
  • Usage scenarios convey when to use the code?

More Information
Optional.  Insert more information as necessary.  This could be background information or interesting additional details.

Additional Resources
Optional.  Insert bulleted list of descriptive links to resources that have direct value or relevancy.

Test Cases:

  • 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.