+972 52-548-6969
What do I expect from guidance?
Phil Haack has a post about code sample taxonomy. He suggests the following taxonomy:
- Prototype
- Demo
- Sample
- Production
- Reference
I am not sure that I agree with his division. From my point of view, demo code need to focus on one single aspect, mostly because we are going to talk around that, and doing that means that I don’t have the time to deal with anything but the aspect that I need to talk about.
Sample code is a more fleshed out example.
I don’t make any distinction between reference and sample apps, maybe the size is different but that is about it.
What is important to follow is that for all of them, except maybe prototype (and I was bitten by that before), I have the same code quality expectations.
Note that I am saying code quality vs. production readiness. Most of the code that you see in demos or sample apps is not production ready. And that is fine.
Production readiness include such things as:
- Parameter validation
- Security
- Error handling
- Failover & recovery
And a lot more “taxes” that we need to deal with.
That does not include code quality. Code quality is a metric of its own, and it is one that you cannot give up. I would be personally ashamed to put out something that didn’t meet my own code quality metrics.
Sometimes, being production ready means that you have to give up on code quality, here is one example, that is understood and acceptable in certain circumstances.
What is not acceptable is to say that this is “Xyz” type of code sample, therefore code quality doesn’t matter.
And code quality isn’t really some amorphous thing. It is a very well defined metric that can be automatically checked. FxCop or NDepend are good tools to have, Simian will give you a lot of value all on its own.
When you put something out as an official Microsoft guidance release, the bar is higher, because whatever you do will be used by other people.
Comments
You have an interesting point, but you may be wrong about the very last part: People are using Microsoft's examples less and less, I think, due to their current track record. At the very least, they are used with a grain of salt.
For example, if you look through a lot of the SharePoint-related code samples on MSDN, many of them contain (or used to contain - not sure if they've all been cleaned up yet or not) blatant memory leaks. . .which their own "best practices for IDisposable in SharePoint", or whatever it's called, have dealt with.
I think code quality takes a back seat way too often in most examples you see on the web. It's pretty disappointing. This isn't just an MS thing, I think. It's like the people who really want to write and be good models are the least fit to do it - kinda like the president. The larger projects that DO have good programming examples in them are often much too large for a user who wants information quickly to get into.
I think at this point, I'm going to look into FubuMVC, rather than the ASP.NET MVC framework - Chad and Jeremy seem to have done a good job on it, at least from what I've heard. What are your thoughts on it, Ayende, or have you not looked at it closely?
Kyle,
I haven't written actual web app for too long.
More than that, I haven't actually taxed a web framework for even longer.
Kyle,
Tons of people still use the Microsoft samples and follow them religiously. Good or bad can be debated on a case by case basis as this series suggests. The range of developer maturity/experience/ability is much wider than many would like to believe.
I think there is difference between code example and code example. And it depends on author of code example. My own examples are sometimes "production ready" and sometimes like drafts that only try to illustrate my point.
But... I am just small man with my small blog. If I where Microsoft... hmm.. I think I had some separate technical press division checking out all code that is going to public. :)
Ryan,
I think you're exaggerating just a bit with, "Religiously." Obviously developer maturity, experience, and ability has high variability; my point was only that I think the people who are "religious" about Microsoft's examples are decreasing by the day. Admittedly, however, that's just an off-the-cuff guess based on all the comments I've seen on the blogs I read. I'm sure there are still many more who, when they copy/paste the MS code, are left scratching their heads as to why it isn't working the way they want it to, and don't even realize all the memory leaks.
@Kyle
See, I think the type of developers that Ryan is talking about are developers who do not read or post on blogs. No one is sure, but many of us fear that they are the in the majority.
I agree with your Microsoft comments above. The samples are usually little more than pseudocode that just so happens to compile. I see so many blatant errors it is discouraging.
And I find that more and more new programmers skip the help altogether - they are programming by Google as I like to put it. They don't even care what they official source says in the docs, they go to the web and search for examples. Now ask them to code something on the day your net connection is down at the office and they fall apart...
And I also agree that samples need to be quality code. Not production ready, but definitely not containing worst practices or memory leaks.
Comment preview