Ayende @ Rahien

My name is Oren Eini
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:


+972 52-548-6969

, @ Q c

Posts: 6,124 | Comments: 45,470

filter by tags archive

How Microsoft should release guidance?

time to read 3 min | 463 words

Phil Haack has a post about code sample taxonomy, in which he asks how Microsoft can ship high quality sample apps:

Obviously, this [shipping high quality samples] is what we should be striving for, but what do we do in the meantime? Stop shipping samples? I hope not.

Again, I don’t claim to have the answers, but I think there are a few things that could help. One twitter response made a great point:

a reference app is going to be grilled. Even more if it comes from the mothership. Get the community involved *before* it gets pub

Getting the community involved is a great means of having your code reviewed to make sure you’re not doing anything obviously stupid. Of course, even in this, there’s a challenge. Jeremy Miller made this great point recently:

We don't have our own story straight yet.  We're still advancing our craft.  By no means have we reached some sort of omega point in our own development efforts. 

In other words, even with community involvement, you’re probably going to piss someone off.

Um, no.

I feel that Jeremy’s point has been pulled out of context. While we may have disagreements about what constitute the future directions in software development, that isn’t actually what cause the community to reject the bad samples from Microsoft.

No one said a word about Kobe because it didn’t use NHibernate, or wasn’t built with messaging or using DDD.

What we reject in those sample app is that they are, put simply, bad coding. There is nothing amorphous about this, we aren’t talking about subjective feeling, we are talking about very concrete, objective and real metrics that we can apply.

Bad Code

Not some omega point.

Bad Code

Not lack of understanding of the platform because the developers writing that were new to ASP.Net MVC.

Bad Code

That would have been bad code if it was written 5 years ago or 15 years ago.

That is the problem.

And I think that there is quite a simple answer for that. Stop shipping official guidance package without involvement from the community.

Create a special CodePlex project where you are being explicit about putting things for review, not for publishing. After the guidance has been published, it is probably too late already.

Get some feedback from the community, then you can publish this in the usual places.


J Healy

I find it odd that an organization which rigorously vets product and press releases - and has a group called Patterns and Practices - is simply failing on the guidance front. Whether via a public or private process, and as you and others have suggested, all such released reference apps need to be vetted in detail by both internal and external reviewers.


Ayende, I agree with what you have said. Bad code is the problem, and if someone can look at Kobe and not see bad code then he isn't a good developer. This isn't nearly as subjective as some people are trying to make it.

What makes me the happiest and least frustrated is to simply ignore Microsoft as much as possible. It took me years to figure that out, but here I am.

Which brings me to my main point: you say that what Microsoft needs to do in order to release guidance that doesn't suck is to subject it to community approval. I agree 100% that this would have the desired effect, in terms of vastly improving the code quality. But step back and look what is happening here (I speak not so much to you but rather to many of your readers). This puts the community into an authoritative position over Micrososft itself. This is exactly opposite of the type of role Microsoft has played in the past, where (in my view, anyway) they have tried to be the Mecca of their platform, the authority on how things are to be done in their ecosystem.

So the question becomes: if Microsoft needs to subject their guidance to the community (and they do) what is the point of their guidance in the first place? Who cares what they think? If the community is the authority, why does Microsoft matter?

(I might suggest that it's a matter of history that has not yet fully played out. In other words, perhaps Microsoft doesn't matter anymore, but most of the ecosystem that has sprung up around Microsoft technologies hasn't figured that out yet.)

Ayende Rahien


That is really great point, and not something that has occurred to me.

I think that the answer is a multi part one.

a) guidance from Microsoft carry weight, and the active parts of the community want to ensure that this has the proper level of quality.

b) the problem isn't with the actual guidance that they put (documents and such), I don't really have much problem with that. I have problem with the code quality that they produced.

c) having guidance come down from the mountain no longer works, and we need to involve more view points. But there aren't many people or companies that are willing or able to produce guidance. Microsoft is one such company, and we want to have more guidance (good one), because in the end, it helps everyone.


Stuart, I agree completely with you. The people at Microsoft who work on the core C# language etc clearly know what they're doing, have a long term plan and are executing that really well.

Everything else from MS should be treated with extreme skepticism.

Ryan Cromwell
Why does Guidance need to be "published"?  Why can't it grow organically while highlighting points in time for their introduction of certain techniques?  Every industry grows and changes as it adapts.  Allow the "Guidance" samples to grow with it.  Providing an IBuySpy, Northwind, 
<your that can grow and change as the tools and techniques do would provide facinating look into the way the industry has changed in 10 or 20 years.
Publications rot.  Projects have a life of their own.
Ayende Rahien


The problem with organically grown guidance that it is scattered.

There is a LOT of value in creating organized, cohesive and structured format for this.

Stefan Wenig

If they get all democratic about guidance, the guidance projects could provide feedback for their higher level framework teams.

Once they start doing that, they might as well have an open discussion about their frameworks without that indirection. This is not about nitpicking on every design detail, but about how an application using that framework should be built (and therefore, how that framework should be constructed in order to support this design)

Who knows, it might happen sooner than we think.



Great point, I'am in the same boat also - ignore all sample apps put out by MS.

It didn't take me that long to figure out because I came out of the java world into ASP.NET 1.1 and the sample apps on ASP.NET (AspPortal, Project Management etc ... forgot the names) where so horrible I could not believe that they came from MS.

Which make me sometimes wonder if that is how "Windows" looks like under the covers.


@Stefan --

To your point, yes, it might happen. But to my point, who cares? :)

I'll give credit to MS for developing the CLI / ECMA-335 and even for giving a nice implementation in the .Net Framework (with the exception that it only works on their platform). But we developers can take it from here.

Microsoft needs to produce good guidance at this point because many people still care what MS says. I look forward to the day when everyone realizes that they, like all corporations, are not the authority on how technology is supposed to be used.


Comment preview

Comments have been closed on this topic.


  1. RavenDB 3.5 whirl wind tour: You want all the data, you can’t handle all the data - about one day from now
  2. The design of RavenDB 4.0: Making Lucene reliable - 3 days from now
  3. RavenDB 3.5 whirl wind tour: I’ll find who is taking my I/O bandwidth and they SHALL pay - 4 days from now
  4. The design of RavenDB 4.0: Physically segregating collections - 5 days from now
  5. RavenDB 3.5 Whirlwind tour: I need to be free to explore my data - 6 days from now

And 14 more posts are pending...

There are posts all the way to May 30, 2016


  1. RavenDB 3.5 whirl wind tour (14):
    29 Apr 2016 - A large cluster goes into a bar and order N^2 drinks
  2. The design of RavenDB 4.0 (13):
    28 Apr 2016 - The implications of the blittable format
  3. Tasks for the new comer (2):
    15 Apr 2016 - Quartz.NET with RavenDB
  4. Code through the looking glass (5):
    18 Mar 2016 - And a linear search to rule them
  5. Find the bug (8):
    29 Feb 2016 - When you can't rely on your own identity
View all series



Main feed Feed Stats
Comments feed   Comments Feed Stats