For Example

I’ve heard complaints about the poor state of example code. Example code, it seems, is ruining programmers across the globe.

Let’s divide the world’s code into two categories: production code, and example code. Much like matter and anti-matter, the two should never meet. They exist for different purposes, and have distinct goals.

The only feature these two have in common is that both production and sample code can be difficult to write. Yes, ask any author – coming up with sample code to illustrate a specific point can be a hair pulling experience. Do I contrive an example to keep the sample as short as possible while getting the point across? Alternatively, do I come up with a “real” example at the risk of complicating the explanation? Like everything else we do, there are tradeoffs to evaluate.

Improving sample code isn’t going to improve the developers of the world. The developer who cuts and pastes from MSDN documentation has other fundamental problems.

Don’t blame bad software on the authors of sample code. Instead, blame the authors of the software.