Reading about Silverlight 2, I stumpled upon Jesse Liverty’s rules for examples, they are simple and almost universal…
Judge for yourself…
1. Keep it simple enough that the example totally focuses on what you are trying to illustrate (but no simpler)
2. Try to use something like business objects rather than cute animals or game objects
3. Don’t show off how clever you are, break the code down into small digestible parts.
4. Use interim variables; they’re easier to catch in a debugger
5. Strip away all exception and error handling and bullet proofing unless you are teaching exception handling, error handling or bullet proofing.
6. Use great variable names so you need fewer comments, but don’t convince yourself that means you don’t need any.
7. Show the output
8. Make no apologies (except when you’re wrong)
Thanks, Jesse… for letting us laymen get access to some of the experience you have gained from writing those 10+ technical books about programming 🙂