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?


Last edited Apr 29, 2010 at 8:25 PM by mycodeplexuser, version 15

Comments

No comments yet.