Code Sample Taxonomy

Apr 16, 2009 code suggest edit

What responsibility do we have as software professionals when we post code out there for public consumption?

I don’t have a clear cut answer in my mind, but maybe you can help me formulate one. :)

For example, I recently posted a sample on my blog intended to show how to use jQuery Grid with ASP.NET MVC.

The point of the sample was to demonstrate shaping a JSON result for the jQuery grid’s consumption. For the sake of illustration, I wanted the action method to be relatively self contained so that a reader would quickly understand what’s going on in the code without having to jump around a lot.

Thus the code takes some shortcuts with data access, lack of exception handling, and lack of input validation. It’s pretty horrific!

Now before we grab the pitchforks (and I did say “we” intentionally as I’ll join you) to skewer me, I did preface the code with a big “warning, DEMO CODE AHEAD” disclaimer and so far, nobody’s beaten me up too bad about it, though maybe by writing this I’m putting myself in the crosshairs.

Even so, it did give me pause to post the code the way I did. Was I making the right trade-off in sacrificing code quality for the sake of blog post demo clarity and brevity?

In this particular case, I felt it was worth it as I tend to categorize code into several categories. I’m not saying these are absolutely correct, just opening up my cranium and giving you a peek in my head about how I think about this:

Prototype Code – Code used to hash out an idea to see if it’s feasible or as a means of learning a new technology. Often very ugly throwaway code with little attention paid to good design.
Demo Code – Code used to illustrate a concept, especially in a public setting. Like prototype code, solid design is sometimes sacrificed for clarity, but these sacrifices are deliberateand intentional, which is very important. My jQuery Grid demo above is an example of what I mean.
Sample Code – Very similar to demo code, the difference being that good design principles should be demonstrated for the code relevant to the concept the sample is demonstrating. Code irrelevant to the core concept might be fine to leave out or have lower quality. For example, if the sample is showing a data access technique, you might still leave out exception handling, caching, etc… since it’s not the goal of the sample to demonstrate those concepts.
Production Code – Code you’re running your business on, or selling. Should be as high quality as possible given your constraints. Sometimes, shortcuts are taken in the short run (incurring technical debt) with the intention of paying down the debt ASAP.
Reference Code – This is code that is intended to demonstrate the correct way to build an application and should be almost idealized in its embracement of good design practices.

As you might expect, the quality the audience might expect from these characterizations is not hard and fast, but dependent on context. For example, for the Space Shuttle software, I expect the Production Code to be much higher quality than production code for some intranet application.

Likewise, I think where the code is posted and by whom is can affect perception. We might expect much less from some blowhard posting code to his personal blog, ummm, like this one.

Then again, if the person claims that his example is a best practice, which is a dubious claim in the first place, we may tend to hold it to much higher standards.

Now if instead of a person, the sample is posted on an official website of a large company, say Microsoft, the audience may expect a lot more than from a personal blog post. In fact, the audience may not make the distinction between sample and reference application. This appears to be the case recently with Kobe and in the past with Oxite.

Again, this is my perspective on these things. But my views have been challenged recently via internal and external discussions with many people. So I went to the font of all knowledge where all your wildest questions are answered: Twitter. I posed the following two questions:

Do you have different quality expectations for a sample app vs a reference app?

What if the app is released by MS? Does that change your expectations?

The answers varied widely. Here’s a small sampling that represents the general tone of the responses I received.

Yes. A sample app should be quick and dirty. A reference app should exhibit best practices (error checking, logging, etc)

No, same expectations… Even I ignore what is the difference between both.

Regardless of who releases the app, my expectations don’t change.

Yes being from MS raises the bar of necessary quality, because it carries with it the weight of a software development authority.

I don’t think I have ever thought about what the difference in the two is, isn’t a sample app basically a reference app?

I don’t think most people discriminate substantively betw the words “sample” and “reference.”

Everyone, Microsoft included, should expect to be judged by everything the produce, sample or otherwise.

yes, samples do not showcase scalability or security, but ref apps do… i.e ref apps are more “enterprisey”

IMHO, sample implies a quick attempt; mostly throw-away. Ref. implies a proposed best practice; inherently higher quality.

No. We as a community should understand the difference.However MS needs to apply this notion consistently to it’s examples.

Whatever you release as sample code, is *guaranteed* to be copy-pasted everywhere - ask Windows AppCompat if you don’t believe me

Note that this is a very unscientific sampling, but there is a lot of diversity in the views being expressed here. Some people make no distinction between sample and reference while others do. Some hold Microsoft to higher standards while others hold everybody to the same standard.

I found this feedback to be very helpful because I think we tend to operate under one assumption about how our audience sees our samples, but your audience might have a completely different view. This might explain why there may be miscommunication and confusion about the community reaction to a sample.

I highlighted the last two responses because they make up the core dichotomy in my head regarding releasing samples.

On the one hand, I have tended to lean towards the first viewpoint. If code has the proper disclaimer, shouldn’t we take personal responsibility in understanding the difference?

Ever since starting work on ASP.NET MVC, we’ve been approached by more and more teams at Microsoft who are interested in sharing yet more code on CodePlex (or otherwise) and want to hear about our experiences and challenges in doing so.

When you think about it, this is a great change in what has been an otherwise closed culture. There are a lot of teams at Microsoft and the quality of the code and intent of the code will vary from team to team and project to project. I would hate to slow down that stream of sample code flowing out because some people will misunderstand its purpose and intend and cut and paste it. Yes, some of the code will be very bad, but some of it will still be worth putting out there. After all, I tend to think that if we stop giving the bad programmers bad code to cut and paste, they’ll simply write the bad code themselves. Yes, posting good code is even better, but I think that will be a byproduct of getting more code out there.

On the other hand, there’s the macro view of things to consider. People should also know not to use a hair dryer in the shower, yet they still have these funny warning labels for a reason. The fact that people shouldn’t do something sometimes doesn’t change the fact that may still do it. We can’t simply ignore that fact and the impact it may have. No matter how many disclaimers we put on our code, people will cut and paste it. It’s not so bad that a bad programmer uses bad code, but that as it propagates, the code gets confused with the right way and spreads to many programmers.

Furthermore, the story is complicated even more by the inconsistent labels applied to all this sample code, not to mention the inconsistent quality.

So What’s the Solution?

Stop shipping samples.

Nah, I’m just kidding. ;)

Some responses were along the lines of Microsoft should just post good code. I agree, I would really love it if every sample was of superb quality. I’d also like to play in a World Cup and fly without wings, but I don’t live in that world.

Obviously, this 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. But avoiding piss is not really the point anyways (though it’s much preferred to the alternative). The point is to be a participant in advancing the craft alongside the larger community. Others might disagree with some of your design decisions, but hopefully they can see that your code is well considered via your involvement with the community in the design process.

This also helps in avoiding the perception of arrogance, a fault that some feel is the root cause of why some of our sample apps are of poor quality. Any involvement with the community will help make it very clear that there’s much to learn from the community just as there is much to teach.

While I think getting community involved is important, I’m still on the fence on whether it must happen before its published. After all, isn’t publishing code a means of getting community involvement in the first place? As Dare says:

getting real feedback from customers by shipping is more valuable than any amount of talking to or about them beforehand

Personally, I would love for there to be a way for teams to feel free to post samples (using the definition I wrote), without fear of misconstrued intent and bad usage. Ideally in a manner where it’s clear that the code is not meant for cut and paste into real apps.

Can we figure out a way to post code samples that are not yet the embodiment of good practices in a responsible manner with the intent to improve the code quality based on community feedback? Is this even a worthy goal or should Microsoft samples just get it right the first time, as mentioned before, or don’t post at all?

Perhaps both of those are pipe dreams. I’m definitely interested in hearing your thoughts. :)

Another question I struggle with is what causes people to not distinguish between reference apps and sample apps? Is there no distinction to make? Or is this a perception problem that can be corrected with a concerted effort to make such labels consistently applied, perhaps? Or via some other means.

As you can see, I have my own preconceived notions about those things, but I’m putting them out there and challenging them based on what I’ve read recently. Please do comment and let me know your thoughts.

Found a typo or mistake in the post? suggest edit

Comments

48 responses

Kirk • April 16th, 2009
How about samples as extensions to a reference app, so you don't need to build the surrounding structure. Use the reference app to provide data when you don't want to re-write the data logic, use the reference apps UI when you are demonstrating data access.
Of course, this means that a reference app needs to be well written, and could be overwhelming -- but at least once we learn it once, we don't need to do it for each sample.
I'm thinking of Northwind, where the DB was the reference DB for soooo many years. We didn't need to understand it fully when someone did a tweak to it, a UI over it etc.
Kirk
Cyril Bioley • April 16th, 2009
@ Kirk
Maybe I was not born yet, but I would be curious to know if Northwind could really be considered as a reference database (according to Phil's definition) ;-)
MARCEMARC • April 16th, 2009
how about a website/app that allows you to upload your code samples for hosting; and from there you can reference them to appear inline within your blog post; samples would appear in a consistent way and could be marked as 'sample' or 'reference' etc. The community could discuss the sample techniques and vote on the production quality of the code; issue warnings; post ammendments; offer advice/links to how it would be better to do the dodgy bits that just exist to make the main point of the example easier to understand. You could score points (double points for being nerdy about microsoft posts); a bit like flickr but for code instead of pics.
N • April 16th, 2009
"What responsibility do we have as software professionals when we post code out there for public consumption?"
If it's official, a lot. Kobe is a disaster.
borisCallens • April 16th, 2009
There will always be "gimme teh codez" copy-pasters.
No matter how good your code is, it is most likely not the perfect solution to every situation and some healthy common sence is needed to evaluate how copy-pastable (a section) of code is.
Sometimes it is possible to demonstrate good code practices by referencing to stub procedures/classes. You don't write a letter of extra code, but because of a descriptive procedure name everybody gets what it should do.
This off course renders you with unrunnable code, but that often times isn't necessary to demonstrate someting.
I personally don't believe in a one-size-fits all answer to your question and no matter what your decision is, being a front man of a great project and being from a large corp will always send some piss your way. Don't let that hamper what you're doing, it has helped me (and no doubt plenty of others) a great deal. Appreciated (piss-free ;)
RuairiSpain • April 16th, 2009
My feeling is that MVC architecture aims to improve code quality for Web apps, it has pushed to improve my architecture/developer/testing skills. Creating one sample MVC app that gets the balance right between flexibility and quality is a tough task.
I think the MVC community would appreciate a simple Reference Code sample for a simple ASP.Net app. It would accelerate the adoption of ASP.Net MVC into the WebForms developer community. For example, I got hooked on ASP.Net MVC because of Rob Conway's MVC Storefront videos. As a sample, the Storefront is great, but it's a lot of code for a novice digest.
So, this is what I'd like to see: a simple real world(ish) example that keeps as close to the .Net 3.5 Sp1 as possible (perhaps giving URLs to point people to alternatives outside Sp1). The sample illustrates the design patterns you'd choose in the different layers (without too much overkill on patterns, it has to be digestible to novices).
If there is a project that already is "Reference Code", please let me know. If not can someone create a simple example of one so we can learn from the Ninjas! I'd create one, but I fear my code quality would not be up to the mark!
Parag Mehta • April 16th, 2009
Hi Phil,
I hope you are defending a case against KOBE. The whole point of using MVC is better decoupled design and controlled html output. Did you even see the CSS class names ?
I know it is fasionable to attack anything that comes out of Microsoft, but it's only going to make our community cleaner.
Just today I was listening to a HerdingCode Podcast about Mac development : They restrict the choices. The guy in the Podcast(forgot his name) said that Objective C programs where MVC by default, there was no way around! They imposed strict guidelines by default. InterfaceBuilder (their GUI tool) didn't even allow manual changing of XAML equivalent UI code. No wonder I have not yet seen a single ugly Mac App. I see tons of rubbish on Windows App world. The point I am making is MVC should be for people who care about architecture so that output comes beautiful by default. So the reference implementation has to be good. Kobe neither had design benefits of MVC nor had any Test benefits.
mat roberts • April 16th, 2009
I learn though example, so samples are pretty useful to me.
I think a sample should:
1) Compile and run - its pretty useless if it doesn't.
2) Be Compelling - i.e. do something I actually want to do - not something contrived to illustrate a command. Compare Kernighan and Ritchie "C" - excellent sample code, with Stroustrup "C++" - rubbish samples showing nothing (and they don't even compile.)
3) Show best practice. How much in production C# have you seen where a file handle is just closed, rather than having the whole thing wrapped in a using()? The thing is though, folks are copying this straight off MSDN.
4) Show unit testing. Folks aren't good at unit testing, so show it in samples to help people learn.
I understand exactly what you're saying. Its difficult to get a compelling, best practice, unit tested sample in a 1 page blog post. Doesn't mean you shouldn't try though.
I think your Demo Code category is problematic. If I need your demo code to learn how to do something, will I be knowledgeable enough to turn it into production code? Probably not.
Joe Brinkman • April 16th, 2009
The problem with the "we'll fix it after it ships" mentality is that it is not real world for most sample apps. Almost every sample app in existence has 0 maintenance dollars allocated to it. It is created, distributed and then abandoned.
That is not to say I agree at all with the sentiment that all code out of MS must be reference code. That line of thinking is ridiculous. The devs at MS are good, but they are not gods. They don't have all the answers anymore than the rest of CS community. They are learning and improving their craft just as the rest of us are.
As a society we have a tendency to put people up on pedestals. Often this is done so everyone has a better target at which to throw tomatoes. The furor over Oxite and Kobe just seems to follow right in line with this mentality.
Steve Willcock • April 16th, 2009
I recently started answering questions from the community on stackoverflow.com, and I briefly came up against the same issues when posting code samples. I strongly feel that if you are trying to demonstrate a particular concept with demo code that it is a good idea not to detract from the concepts you are trying to put across with extraneous infrastructure code and 'good practice'. Anytime someone tries to include these extra elements in simple code samples they are:
1) Diverting attention from the pertinent bits of the API they are trying to demonstrate.
2) Making assumptions about the readers context / situation - where the code is being used, how it will be run, etc.
3) Wasting their own time
4) Wasting the readers time
5) Opening themselves up to comments on the bits of the code that are NOT pertinent to the api under discussion
6) Missing things out - you can't put ALL the best practise you know into a 10 line code sample, so don't try. It's just a sample :)
In the end, some people will find the few lines of code they want, and copy / paste it without another thought, whether it's surrounded by reams of 'best-practise' code or not. Of course, for someone in your situation working for Microsft, it's not quite that simple. Maybe the best idea is to include a short standard disclaimer on every sample (or a link to a disclaimer), then you can forget about it and concentrate on demonstrating the particular apis in question to the best of your ability.
Karl • April 16th, 2009
The problem with a complex taxonomy is that it gives an easy out for people to write shitty code, as opposed to making them accountable. Maybe we should stop trying to play word-games and call a spade a spade.
In an iterative setting, a prototype is simply a feature-poor version of the final product. A prototype should be unit tested, should be cleanly written, should following DRY and SOLID principles. You either write clean code and adhere to best practice, or you don't. I don't know of any programmer who writes really bad code in one context, and then beautiful code in the next.
I see:
-Utility code/throwaway code like 1 time importers or stuff you write in SnippetCompiler.
-Real Code
The level of DRY/SOLID/Unit Tests of Real Code should be proportional to its complexity & size. I mean, if you start off with a rough method you might have some ugliness, but you better clean it the fuck up before you add a 2nd class. And then before you start referencing a different layer, you better add your unit tests and start thinking about switching to TDD.
The idea that you can "prototype" anything complex (say that has a UI and/or hits the DB) without caring much for design and craftsmanship is foreign to me (unless you are using some scaffolding code, but then we're talking about a few lines of boilerpoint code, as opposed to custom code).
Sergio Pereira • April 16th, 2009
I agree in general with your classification of the different levels of source code. Extra care should be taking in the wording that goes with the sample publication, though.
In the particular case of Oxite and Kobe, they were clearly announced (at least initially) as references or guides.
To make matters worse, a large part of people examining the published source code are developers that have probably been extolling the virtues of the MVC approach, and they get upset to see MVC code that has any sort of serious shortcomings (and even nits.)
I'd dare to say that many worse problems exist and have always existed in other samples or reference implementations published by MS. It just happens that were dealing with a loud crowd here and they have good feedback to give.
Keep the samples. Be zealous with the labeling of the code.
Craig Stuntz • April 16th, 2009
I wonder if the real issue here is not that Microsoft, occasionally, posts less-than-optimal samples, but rather that there is not an official "best practices" demo for MVC. (Your reservations about "best practices" noted and agreed.) In other words, the faults of Oxite and Kobe would be more easily overlooked if there were another project which existed for the explicit purpose of demonstrating a simple, but well-structured application.
Something like NerdDinner, perhaps.
One thing that I have observed within the ASP.NET MVC community is that a lot of people really want this. MVC is brand-new, few books are out, and opinions about what constitutes good style are still being formed. Microsoft has great guides for "good style" when writing APIs, for example.
In other words, I think that part of the reason that the criticisms of Oxite and Kobe have been so over the top (the applications are imperfect, but I think the nerd rage is unwarranted) has nothing to do with those applications, per se. Instead, the "rage" comes from the fact that they do not meet a particular need that people have, and that they were probably not intended to meet.
James • April 16th, 2009
Couldn't agree more with Craig about there not being any "best practices" for MVC. The Storefront and NerdDinner code is the closest to it but still lacks a lot.
Steve • April 16th, 2009
I don't expect a full blown architecture example to see how to 'create an ActionLink' in asp.net mvc.
If people are going to copy and paste some sample into their code without thinking about what it does, that is on them, not on you.
If you are creating an application as a 'best practices in mvc' as a sample, then sure, you should apply all the best practices.
But a simple example like what you posted in your last topic... no way, I don't want all that - something simple that the developer should see the pattern and build it how they need to in their architecture.
So, in summary - I don't want some full blown best practices sample project to see 'how to create a grid in jquery'. If I'm looking for a best practices application, maybe I'd do what Billy McCafferty did with Sharp Architecture - with the entire concept being 'here are good practice to use when building a asp.net mvc app'.
I wouldn't want to download and install all that just to see a 'how to create a grid in jquery' - please no!
Jeff Craig • April 16th, 2009
I've tended toward using quick-and-dirty examples on my blog as well, since the thought of someone just copying-and-pasting my example generally bothers me, but I think it's right that, yes, many people will just c/p without any regard for code quality. It's the 90/10 problem that Atwood is always going on about.
To help mitigate this problem, I'm thinking about starting to use GitHub's Gist feature, which allows me to upload code-snippets I can host in my blog, but ones that can be forked and improved upon, all while being stored in source control. I think this sort of communal paste-bin idea can allow you to start quick-and-dirty, but improve the code over time, but still be able to show the evolution of the idea.
Erik van BRakel • April 16th, 2009
Phil,
I recently started reading Fowler's Refactoring book (or is Tome more fitting?). In the introduction of the first chapter he mentions the way he approaches the samples in the books. Basically what he's saying boils down to this:
- He tried various approaches, from very simple to complex;
- When he tried to use even the most moderate form of a complex sample, his chapters would reach well over 100 pages each;
- When he tried simple samples, he felt the code didn't really show the advantages of the methods he discusses.
What he did was just instruct his audience (aimed at semi to very professional programmers) to view the samples in the context. Create a background story for the sample, describe the overview of the system it's used in and work on isolated samples. By looking at the samples in that context, or overview if you will, the samples suddenly make a lot of sense. I don't think I'd view them like that if he didn't mention it.
So, to add to your sample code definition, I agree that it should only focus on the important part. But a big part of that is highlighting the important things (bold face?) pushing the less important things to the side. If that's what people are doing, I think a lot of samples make a LOT more sense. Also, applying the same sample in more than one case should improve many samples out there.
All in all though, I think the samples for the .NET framework are not that bad. If you compare them to, for instance, the samples available for PHP, there's a world of difference.
Brian Brewder • April 16th, 2009
I agree with @Steve, sample code should be short and to the point. Adding a bunch of "best practices" just gets in the way of learning the concept that you are reading the code for. If developers don't know how to do proper error handling, I don't think an article on how to use the JQuery grid is the appropriate place to teach them. I would also prefer to have some poorly written sample code then no sample code at all.
Towards the end of your article you ask "Can we figure out a way to post code samples that are not yet the embodiment of good practices in a responsible manner with the intent to improve the code quality based on community feedback?" You can always post the code sample as a screenshot :). You can't cut-and-paste from an image and the extra effort to type it out might be enough to make the developer realize they have to write more code.
Haacked • April 16th, 2009
@Joe Well I think Oxite is one counter example. They were actually deployed on the "sample" app before releasing. Thus they had to and did fix it later? Is that acceptable?
@Everyone The point of this post isn't to defend any particular sample. In fact, much of it is to spur thought externally and internally about how we go about doing this. I really think that it's a surprise to those on the inside when people trash samples so vigorously. I hope my post helps clarify to internal people why the community feels so strongly about it.
At the same time, I want to ask questions so we can improve the process.
For example, I think the Kobe team in their minds were trying to demonstrate the concept of building an Web 2.0 architecture consisting of multiple applications working together, MVC was simply an ends to that means. They were brand new to ASP.NET MVC and weren't seeking to build a reference ASP.NET MVC application.
But based on the reaction, I think the lesson here is (and this is partly the question I'm asking in this post):
People don't make the distinction between samples and reference apps when it comes from Microsoft.
This team was well aware of the Oxite debacle. They told me they weren't promoting this app as best practices or reference app. However, the lesson here is that even in good faith, it didn't turn out well.
@Karl what do you think the solution is? For the sake of argument, let's assume the next team comes along and they really believe they're writing good code and want to release a sample. What should the process be? I can't send an email to all employees saying (Hey! Learn SoC, DRY, etc... or don't release your sample).
Wish I could. But I can't.
So a lot of groups at Microsoft (it's a big company) are going to learn the hard way. They'll release something thinking it's fine, and the community will review it and point out the flaws, and then hopefully (as in the Oxite case) they'll revisit and fix it.
It sounds to me that nobody feels this is an acceptable process for MS to learn and improve. Part of my question is whether there's a better way.
Should we have an internal review process for every sample? I don't think that'll scale. Kobe did present some of their code to me and I gave them feedback. I didn't do a line by line code review, though. I didn't play around with their source myself. I wish I had, but having me and my team review every sample MVC app is not scalable.
Do you have something else in mind?
Karl • April 16th, 2009
Before I get to the meat of the discussion, the problems with Kobe aren't MVC specific. You could take out the entire UI element and all of the problems persist. I'm afraid that our criticism has focused on this being an MVC sample, despite the problems being non-MVC related. In other words, the fact that the team didn't intend for this to be taken as an MVC reference, doesn't really explain why their domain and data layers suck, why they didn't write unit tests, or why they couldn't agree on reasonable coding styles from the get-go.
About the process...I fully endorse Microsoft's willingness to try and learn. I'd be pretty hypocritical if I didn't, because you don't have to go too far back into my code to find similar crap. You do think the Oxite situation would have made people @ MS (yourself including) far more sensitive/aware.
A big issue for me with Oxite, and to a lesser extent Kobe (maybe because Oxite corrected my expectations), is for Microsoft to actually PULL these downloads. Extreme arrogance I know right? But I figured that my outrage would be enough to get the download links pulled and an message explaining why posted. I don't enjoy publicly lashing out (its tiring), and I sincerely feel sorry for how I handled Oxite - I'm a pretty passionate programmer, and I *know* *I* would have taken it quite personally had someone done that to my code. Nonetheless, I feel equally sincere that these examples can really SCREW over individuals and companies. I actually worry about some poor programmer somewhere, who might be a little junior, not the best in the world, and going down the Oxite/Kobe road. I know these kinds of programmers, and I think they make up a large portion of the .NET ecosystem. They lack confidence, or experience, or something, but they are unable to critically think for themselves or question Microsoft. So that's my angle, and that's what I think Microsoft can reasonably do to make all of this a better process.
It'd be great if things could be more proactive. But I understand that there are 80K employees, under different teams, of various skills, and with different goals. Under those circumstances at least be more reactive. We've raised the flag. I'm hoping that some decision makers at Microsoft have now taken the time to more thoroughly review Kobe. If those people agree with us, PULL the download and put up a warning about why. I see every minute that goes by, ever download that happens, as having the potential for a small disaster. I still can't understand why Oxite wasn't pulled. I'm pretty sure it's cultural - it would mean having to admit you (Microsoft) was wrong.
You want the freedom to learn and improve, but in the months it takes to fix it, you're willing to let thousands of people learn from the initial disaster. That's just irresponsible and shortsighted.
2nd comment coming up..
Haacked • April 16th, 2009
One interesting suggestion I heard is that "guidance" should be more centralized and driven by P&P. Maybe they don't create ALL guidance, but they should be involved in all of it. They can provide the expertise to get community involved and to review samples, resource kits, etc...
What do you think?
Dan Sylvester • April 16th, 2009
demo reference whatever all code falls between these boundries:
Code that can't reasonably fail.
Code that can easily fail.
Sam Camp • April 16th, 2009
"What responsibility do we have as software professionals when we post code out there for public consumption?"
1. It grows with the size of your audience.
2. It grows when the code is a new concept to your audience.
3. It grows with the amount of code you "put out there".
Joe Brinkman • April 16th, 2009
@Phil - my comment on sample code not being updated is when it truly is a sample. I have no problem with releasing samples early to get feedback, if there is a commitment to actually incorporating the feedback.
I personally view sample code is "throwaway" code. I don't use it to learn best practices or to incorporate into my app. I use them to see how a single specific feature is used. I do expect API calls and the like to be best practice, but I don't really care if all the error handling is in place, whether there are 10,000 unit tests for your 100 LOC or whether you favored inheritance or composition.
Just like the bubble sort is used to introduce CS students to sorting techniques, the sample app should INTRODUCE users to certain concepts. It is not an end point, but a beginning from which you can move on to the real solution.
Kevin Dente • April 16th, 2009
I think "published" doesn't have to be a binary thing here. There's different levels of publishing. There's something in between "show nothing" and "post the source and tons of content with a big splash on the www.asp.net site". For example, another level might be "throw the source up on Codeplex, say it's a work in progress, write a blog post soliciting feedback."
Karl • April 16th, 2009
If people at Microsoft don't know DRY or IoC maybe they shouldn't be allowed to lead the development of a customer/developer facing application? Whoever authorized the Kobe team to release source code probably should have had a better idea about the level of expertise the developers had in the area.
I tweeted this earlier, and I think part of the problem is that you can't easily hire good developers to build sample applications. I equate good development with passion, and most passionate developers I know want to do more than what amounts to glorified documentation.
The other problem is that Microsoft excels at building compilers/operating systems/file systems/frameworks but not the type of Application the vast majority of its developers build. I took a couple compilers course, it was neat. The people who were really good at it were geniuses. They were easily twice as smart as I was. But I talk to them now, and they've _never_ heard DI or SRP. They'd be just as lost doing what I do as I would doing what they do. I don't know much about medicine, but I'm going to guess that its like a brain surgeon swapping places with a heart surgeon.
Paul Vick, Scott Gu, Anders - I wish I could be as smart and skilled as them. But I'm also really thankful they don't spend weekends writing banking software that I'm going to have to maintain.
My solution is for Microsoft to put a real team of enterprise developers together - get Ayende, Chad & Jeremy, Scott Reynolds and Scott Allen - and have them build REAL systems. Make them a part of a skunk works program. They come up with a real web 2.0 idea(yes, that means you need to come up with something better than another blog engine), and release the code open source. Microsoft is in the unique position of being able to release real applications/services & leverage that source code as documentation for its developers. Imagine if Twitter, Facebook or Digg had been built by such a team. That's honestly my dream. (stackoverflow comes to mind as a potential candidate too).
It might be an expensive team to put together, but you'll get a a real property and some real guidance.
(P.S. - My idea was My Property. By Reading The Above Paragraphs, Microsoft Owes me $100 000USD - Make Certified Check Payable to Karl Seguin. Due May 1st, 5% monthly interest thereafter).
Kyle Szklenski • April 16th, 2009
Here's a thought, and it may not be a good one. I'm just thinking off the top of my keyboard here. What if the sample apps that MS is intending to put out had an anonymous mailing list where they'd post code samples of portions of the samples long before the samples go to the web? These lists would be open to anyone to respond to - but it's an opt-in scenario, obviously, and all email addresses are anonymous, except obviously for security checking and such.
Each sample wouldn't have to send out a lot of examples of the code - if they can get down a style that most people on the lists like for a specific piece of code, then they can use that as an example of how to code the other parts.
I'd like to think of this as almost an anonymous code-review system. There would be problems with this approach, of course. You'd run into issues with people getting into arguments over the code (very likely), with dry-spells where other people are just too busy (less likely, given that anyone can sign up), with still having the possibility of shoddy code slipping in due to the reviewers' suggestions not being what the general audience is looking for, and so on.
This would go out earlier than even the Codeplex project - not sure how you'd manage that, though. Hm, maybe you could put the initial project onto Codeplex, but not officially "released". People would sign up for said list there. Over time, as things are ready to go up on Codeplex, they're sent to the list for review. Once the "OK" comes back, they're posted. Development would be slower, since you have to deal with feedback, but presumably the quality would sky-rocket.
Good, bad? Any thoughts?
Eddie Butt • April 16th, 2009
I like the list of code categories. I can't think of any others. I'm sure someone will, though.
Personally, I believe the onus is on the publisher to clarify the intent of the code. We do it internally at my company. We add disclaimers to a given document stating what is purposely not standard (no error handling, no application logging, business logic in wrong layer, fully qualified class names instead of Imports, etc.) for clarity in code samples.
Maybe one of the categories is Flame Code? The purpose being to generate "discussion" on the interwebs.
Kyle Szklenski • April 16th, 2009
@Karl, that's an interesting idea, paying Chad, Jeremy, Ayende, etc to produce their sample applications. I'd thought of a similar thing earlier. I think it wouldn't necessarily work out though, aside from the investment. Unfortunately, it might set precedents that cannot be maintained in the long-run. Furthermore, while there's quite a few really good developers out there like those guys, they both cost a ton, as you already mentioned, but they also have considerably less time. Even if they're being paid to do stuff, they still have to fit it into their schedules. That's why I suggested the anonymous mailing list method above - enough people could sign up, and even if some low-quality ones get in, in general, higher-quality stuff is going to come out. That, plus the fact that it would be virtually free for Microsoft, and very good for them, should make it the better deal for 'em.
Karl • April 17th, 2009
Kyle:
I should have been more clear. These guys should be hired as blue badge. I consider this an extremely important hole that should be filled, and hiring a team of 4-6 guys to work FULL TIME on software they are passionate about is the only solution I see.
The code review idea is good, but I see time problems with that as well. A lot of us wouldn't review code pre-release for lack of time. I know that's a little unfair - we won't review your code BEFORE you release, but we'll bitch about it really loudly AFTER you release, but that's the reality.
meisinger • April 17th, 2009
@Karl - that is just nieve. to think that if someone didn't know IoC that they couldn't lead a customer facing team is just... well... wrong. what's next? if they don't know repository pattern they can't lead? if they don't know parallel computing they can't lead?
the solution needs to transcend buzz (MVC being one of them)
i hate to break it to you but not every project needs IoC or should use MVC
i think the solution should be to stop the sample apps and reference apps
i think focusing more on what the framework can do and how to use it is more important. the prototypes and walk throughs about the MVC framework have been good. no need to go any further than that.
look at the walk throughs for PowerShell and WCF
those are give enough to explain what the bits do and how to start using them but the rest is up to you
then the communitiy can go off and educate others on how to use the newest bits in their every day life
Kyle Szklenski • April 17th, 2009
@Karl, yeah, there's no way they'd go work for MS. I seriously think that no amount of money would get them to do that, although I could be horribly mistaken.
And yeah, I pointed out the thing you did in my comment - people just not having time to review things, though I see why yours is different (they wouldn't even sign up for the service, let alone actually contribute). There could be an incentive program there, though - whether it be a contributor's badge or something, or even money. Giving out a small amount of money (say $50 per good contribution, as determined by the team) for a list of 10 reviewers giving one review a week would be $500 per week. That's really not that much, but would provide a pretty big incentive for some people, I think. I know that, even with my well-paid consulting position, if I were to get a book at the end of a project that I helped review, that would make me really happy and encourage me to help that much more.
Karl • April 17th, 2009
@meisinger:
You're encompassing everything we generally say is wrong with Microsoft development division. 1.5 years ago, Jeremy Miller wisely warned that:
"For a little too long the .Net community has put too much focus on learning API and framework details and not enough emphasis on design and coding fundamentals"
SRP, DRY and IoC (note that I didn't say DI) are fundamental - they aren't flavor of the month. They transcend and predate current languages and frameworks.
The only projects that ought-not use IoC, DRY and SRP are those that don't want to be maintained.
Kyle Szklenski • April 17th, 2009
@meisinger, I'd thought of that one, too, but it kinda shows a lack of enthusiasm for the product, don't you think?
Back to the topic at hand, I'm of the opinion that code quality should not be left by the wayside in all but the prototype code, or what I tend to call PoC code. PoC code can be total garbage, and is just a way of finding out if something is even possible to be done the way you were intending. Everything else should have a minimum of code quality - it doesn't always have to be all design patterns and principles, but it should all certainly follow the same naming conventions, show relatively good design, etc. As I said on Ayende's blog, I think anyone who writes a 60+ function interface doesn't really understand the basic design principles (such as the interface segregation principle). I agree with whomever said that the problems with Kobe and Oxite were not strictly MVC-related.
Craig Stuntz • April 17th, 2009
Phil, I agree that having P&P involved is a very good idea.
meisinger • April 17th, 2009
@Karl - point taken
@Kyle - true enthusiasm comes from me and not Microsoft. and i think you are kind-of making my point. if Microsoft releases a new Message Bus framework and nobody in the communitity thinks that it is worth it or it misses the mark then i don't care how enthusiastic they are...
@Phill - the point being, Microsoft does things really really well. and i think that they are turning the corner as far as becoming more transparent in how they doing things and how things are made better. i for one, however, do not look to Microsoft to train or teach me how to write applications regardless of the framework or bits they are presenting
in there lies the problem
posting or releasing sample/reference applications does nobody any good if you don't trust the source
does that make sense?
when i look at what you, Karl, Jeremey, Oren, Joe D, Scott H, and even Eric L post and talk about... i get it. i understand where you are coming from and what you are offering
you all help me learn. it could be on Java, Haskell, F#, Lisp, or what ever and the point still remains
when Microsoft as a company (which is the key point here) releases something... who are they? who is posting the code? who wrote it?
let's make this simple. if i posted code or an application and said it was a reference application on how to do MVC... not only would it take years to wait for the laughter to die down but nobody would take it seriously.
why is some group or some team from Microsoft that nobody has heard of any different than i am?
so again in my mind... the solution is to stop making sample or reference applications
start getting these guys who lead these teams, groups, projects, or what ever out in space. let the communitity decide who they want to hear from. then when those people send out reference applications and sample application their audience is well targeted
i wouldn't expect Scott Gu to write a reference application because that isn't what he does. i would expect him to show me some new bits on what they are working on. so where do i go to get the latest scoop?
i wouldn't expect you [Phill] to write an application about Share Point. if you did... i wouldn't take it as a sample app or a reference app, i would understand that this would be a prototype or something you are trying out
i really hope that makes sense
Will Dean • April 17th, 2009
Can I put a vote in for NOT rushing to implement a review process so extreme that no one can be bothered to ever release anything like this again.
A bit of perspective about some of the criticism is needed - some very opinionated bloggers have written some very strong criticism based to a significant extent on a mixture of their own preferences and current fashions (which will be gone again in another couple of years). Then dozens of sheep have piled in bleating enthusiastically and theatrically sheeshing and face-palming over utter trivia.
We cannot have it both ways folks - we can't have MVC or IronPython style fast release cycle and openness while looking for SQL Server perfection (hmmm).
The bazaar is noisy and stinks, and the cathedral is quiet and perfumed. Half a dozen years ago there was much fashionable ranting and baa-ing on that subject too, and in case any of you can't remember, it was the bazaar that won.
Louis DeJardin • April 17th, 2009
Maybe include a non-intrusive call to action?
public ActionResult Foo(string bar)
{
//TODO: http://asp.net/mvc/bestpractices/controlleractions
var blah = Yadda.Yadda();
return View(blah);
}
Keeps code clean, highlights the absence of some practices, but also tells you what to do if you do cut and paste. And as recommendations evolve it's not leaving an archeological trail of the progression in the sample code.
Haacked • April 17th, 2009
How about this Louis?
public void SomeSampleAction() { throw new CutAndPasteException("Hey, this is sample code! Don't copy it!"); //... bunch of sample code. }
Louis DeJardin • April 17th, 2009
I'm guessing you'll find a lot of
public void SomeSampleAction()
{
try
{
throw new CutAndPasteException("Hey, this is sample code! Don't copy it!");
} catch {}
//... bunch of sample code.
}
in code reviews. ;)
Good ol' "catch {}". The "on error resume next" of csharp.
Thanigainathan.S • April 19th, 2009
Hi,
A very nice article. I will try to follow the guidelines.
Thanks,
Thani
Peter.O • April 19th, 2009
The beauty of demo code is that it actually 'demonstrates' without much noise and clutter.
The danger of demo code, on the other hand is that people may be learning from from it than it intends to teach (eg: style).
So, why don't we standardize this: Let someone start an RFC for formal source code class (SCC) taxonomy. We can start with Phil's names but I will like a class of SNIPPET added. In which case, you expect nothing, require nothing. And the default should be snippet!! Then, everyone posting a piece of source code should mark that code with the appropriate SCC as a comment decoration on the code or part of the documentation, whichever is appropriate. eg:
SCC: DEMO
// source code follows
SCC: REFERENCE
// source code follows
Freddy Rios • April 20th, 2009
I haven't seen the new sample app, but I am sure many are just resonating what a few say.
After all, how many out there really master most of these things? not only that, how much time have happened after they really learned it?
I personally think we are reaching a point where a lot of stuff is maturing, but expecting every team/person to make the change right away is unrealistic.
Actually, I have seen many explanations of these approaches that are flawed, revealing the writer doesn't have full understanding of all the factors involved on the value we get from some of these. If we don't keep reading and learning, there wouldn't be much info to move forward.
We need to move on, change will take time. Some will move faster than others, but we need to remember there is no "upgrade all developers" button.
Remi Despres-Smyth • April 20th, 2009
The assumption here is that people should be able to distinguish between the concepts that sample code is meant to illustrate from those other areas that are secondary.
A programmer with a certain amount of experience will be able to separate the good from the bad, and take away from sample code what is intended. A whole other group of programmers will not, or will not know where else to look to fill in those holes. When looking at new tools and technology, the challenge is greater, because a person's previous experiences do not necessarily translate directly.
I suspect a lot of people looking for answers end up finding sample code, and treat it as the answer. And then get condescended by the rest of us, for not understanding the difference between "sample" and "reference" code.
My $0.02.
Alex Maitland • April 21st, 2009
Keep Kobe, it's a great example of what a lot of production applications look like. Then release Kobe v2 and a series of articles detailing it's re-factoring to best practices.
Probably best to release a number of stages, possibly even get a number of community volunteers to take charge of each stage. Example:
v1.1 - Improved error handling (remove all the copy and paste code that exists currently) (DRY)
v1.2 - Improved data access
v1.3 - Reduced code complexity (Single Responsibility)
v1.4 - etc.....
v1.5 - etc....
Just a though.
Jeremy • April 22nd, 2009
argh, im a 16 year old kid who wants to learn code. anyone have any tips?
Jeff • April 24th, 2009
I think a good reference implementation would cover localization since there are so many ways you can do this in MVC (Multiple Views in different languages, Resource Files, Database Model Driven localization).
This seems like one of the major concerns in web site development and I am not sure the best practices for doing this in MVC.
I think what would be great is for people to post suggestions on what areas they would like to be covered in such a project and then have a community microsoft build it.
laptops under 300 • December 18th, 2009
Sample codes could be helpful, but there is a lot more that will need to go into it.