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.

Comments

Sahil Malik
Monday, March 14, 2005

I agree man. I've heard people criticize books because they present the simplest situation and the simplest code.<br><br>Well if they wouldn't do that, a book would be about 4000 pages, and you'd be payin' about 400$ for it, and you'd never read it all anyway.<br><br>Not to mention it'd take 2 years to write.<br><br>Sample code - and - Real code<br><br>Are Different !! <br><br>Get used to it !!<br><br>The real folks to blame are the heavy duty copy pasters who don't really understand or bother to understand.

John
Monday, March 14, 2005

I think the problem isn't 'sample' code vs. 'production' code. I think the problem is the lack of 'sample production' code.<br><br>No-one sits developers down and explains to them how to write effective production code. Especially not at university.<br><br>The problem with production code is basically that logging, validation and exception handling frameworks/methodologies need to be in place to handle those aspects, and that there aren't good standard tools and practises for these. (And in the case that there are, there is 'religion' or 'corporate agenda' clouding widespread adoption)<br><br>Oh, that, and all software sucks..

Scott
Tuesday, March 15, 2005

I'm thinking it would be a good idea to pick an open source project every now and then and just read the code. It's a bit like looking at 'sample production code'.