Sunday, September 26, 2010

Code Sample Types

by J.D. Meier via J.D. Meier's Blog on 9/26/2010 10:09:23 PM

As part of rounding up our available developer content, one area I can’t ignore is code samples.  Code samples are where the rubber meets the road.  They turn theory into practice.  They also help eliminate ambiguity … As Ward Cunningham says, “It’s all talk until the code runs.”  This post is a quick rundown of how I’m looking at code samples.

Code Snippets, Code Samples, and Sample Applications
I’ve found it useful to think of code samples in three sizes: code snippets, code samples, and sample applications.  Sure there are other variations and flavors, but I’ve found these especially useful on the application development and solution architecture side of the house.  Here is a quick rundown of each code sample type:

• Code Snippets - Code snippets are the smallest form of a code sample.  They are a few lines of code to show the gist of the solution.  They can be used to show product documentation or a particular API.  They can also be used to show application development tasks.  For example, a snippet might be just a few lines to show how to connect to a database.  Usually code snippets are used in conjunction with code samples to walkthrough the implementation and show pieces along the way.
• Code Samples /Code Examples - Code samples are modular code samples that illustrate how to solve a particular problem or perform a specific task. They are bigger than a code snippet and smaller than a sample application.  In fact, a common use for code samples is to show how to perform an application development task, such as how to page records or how to log exceptions.
• Sample Apps - Sample applications are the largest form of code sample provided as guidance. They are provided as to demonstrate application design concepts, and larger processes or algorithms.

Additional Types of Code Samples …

• Application Blocks – Application Blocks are reusable implementations of libraries or frameworks for recurring problems within application domains.  For example, within line-of-business applications (LOB), this would be caching, authorization, aggregation, etc.
•  Frameworks – Frameworks provide solutions for cross-cutting concerns.  They can be lower-level frameworks, oriented around code, or they can be higher-level frameworks, oriented around application concerns.  Enterprise Library is an example of an application framework, similar to Java EE APIs.  In the case of Enterprise Library, the APIs provide a common set of features for solving application infrastructure concerns.
• Reusable Libraries – Reusable libraries are code samples packaged in a reusable way, such as a .NET Assembly. They typically encapsulate a set of related APIs.
• Reference Implementations – These are scenario-based, working implementations of code. A reference implementation might be a reusable library or it might be a framework or it might be a sample application.  In any event, it’s a “reference” implementation because it’s code that’s been implemented as an illustration to model from.

Examples
Here are some examples to help illustrate code snippets vs. code samples vs. sample applications: