Code Example
Summary
Examples that illustrate proven coding practices for a scenario in context.
Example
Schema
- Title
- Applies To
- Summary
- Objectives
- Scenarios
- Solution Example
- Problem Example
- Test Case
- Expected Results
- More Information
- See Also
- Related Items
Test Cases
Title
- Does the title distinguish by product or version where possible?
- Does the title distinguish it from related examples?
- If technology is in the title, is the version included?
- Are important nouns a user might scan for towards the left of the title?
Applies To
- Is it clear what technologies or products this applies to?
- Conversely, is it clear what technologies of products this does not apply to?
Summary
- Does the description crisply summarize the solution?
- Is the intent of the code clear?
Objectives
- Are the user objectives for choosing this code identified?
- Are the objectives of the code identified?
- When would a user need this code example?
- Is it clear why the solution example is preferred over the problem example?
Scenarios
- Are the example scenarios based on real solutions seen in practice?
- Do the example scenarios help highlight when to use the code or when not to?
Solution Example
- 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
- Are comments concise enough so that they does not break the code flow?
- Are the mistakes clear?
- Are the patterns and variations of the problems clear?
- Are the patterns and variations of the problems clear?
Test Case
- Is setup Information included?
- Does the example call the functional blob in the Solution example?
- Can you copy+paste the code and execute it?
Expected Results
- If you run the Test Case, do the Expected Results match?
More Information
- Is the more information essential to put here or can you get rid of it?
See Also
- The links starts with the pattern "For more information on X, see ..."?
- The links are directly relevant versus simply nice to have?
Related Items
- list of related guidance items?
Additional Tests to Consider When Writing a Code Example
- Does the title clearly state the action to take?
- Does the title start with an action word (eg. Do something, Avoid something)?
- If the item is a MUST, meaning it is prevelant and high impact, is Priority = p1?
- If the item is a SHOULD, meaning it has less impact or is only applicable in narrower circumstances, is Priority = p2?
- If the item is a COULD, meaning it is nice to know about but isn't highly prevelant or impactful, is Priority = p3?
- If this item will have cascading impact on application design, is Type = Design?
- If this item should be followed just before deployment, is concerned with configuration details or runtime behavior, is Type = Deployment?
- If this item is still in progress or not fully reviewed, is Status = Beta?