Explaining a concept: Does showing code early make it clearer?

I guess this is a question that may interest many, so please discuss! :-)

Now, imagine you want to show people you work with a concept for future development (like a new product or a new technology you want to introduce).

Does it make sense to 开发者_StackOverflow中文版show code early or would you go with the PPT first? Or what would you recommend?

+1 to Stijn, because really, that's all that matters.

But, it really depends on what you're doing. What is your "concept"?

• An API (e.g. mapreduce)?

Show the code of the API, don't waste people's time with the implementation code, that's not important - "hey, check out how I iterate over your input! it's so clever!". Nope. Nobody cares. If your API is wonderful, it will get used, nobody cares how crufty the code is to make it work.

• A product (e.g. facebook)?

Show the code? Nobody cares. Not even facebook cares (if they did, why would they use php? I kid!). Blow their mind with a demo of the half-complete prototype that does a few things poorly, but shows how great it can be.

• The implementation itself (e.g. a new std::sort routine)?

A lot of people might be interested in seeing the innards. Especially people on SO. So, publish the code, or a whitepaper, when you get something working. It's not "my twitter clone is gonna be sweet, check out how cool my TruncateTo140Chars() function is!". On the other hand, you can get quick feedback on your new implementation's approach by showing your algorithm (in code or pseudocode). You can show benchmarks, which is better than "this code should be faster because I do one less compare with zero".

Please just prototype, get something demo'd that your Users will care about. Only worry about the code if that's what your users want to see (It's usually not).

I like the no-bullshit approach of a proof of concept. Just blow them off their feet and prove that it works.

It depends on the audience and the nature of the product. If the audience and/or product is considered "technical" than consider presenting code. However, you should make it an integral part of the presentation not the entire thing.

I don't believe it is very useful to show your code early. "Us" technical people are always proud to show off our new technical details and ideas. However, people using the products and technologies are only interested in what they can accomplish with it. They will often not share your enthousiasm of the techniques, in this case the code.

My advice is to stick with a more general approach, explain why it's useful and how it will make their lives better. To add a car-analogy: people want to know how much horse-power it has, not how a combustion-engine works!

These implementation-details might however be interesting to your co-workers!

If it really isn't tech people at all, then I have found out that paper models works great. People are scared to criticize when it has been coded, it much easier (and cheaper) to scrap a paper model then the real thing.

When showing a concept of a website/application to a non tech, draw the different pages, the login dialogs etc.

When showing a concept to a fellow developer (if he just don't get it) draw the different classes on paper and show the relations. UML could be useful here if both of you know the syntax.

Else if you got the time, I would say, blow them away with a full implementation :-)

I agree with rtalbot. If the audience is non-technical, perhaps future users, or your boss, I'd go with some diagrams. Perhaps Use Cases. Show them what you can do with it. If it's small, and your friends are nerdy, code up a smoke-and-mirrors demo.

Show customers / stake holders the prototypes early, and review the code among peers later.

Stake holders control what functionality you want to deliver (finding this out early is key to delivering something profitable / useful).

But to increase code quality, code reviews are extremely powerful if done at the right time. My experience has been that doing this towards the end of an iteration provides the most bank for the buck. Your mileage may vary in terms of the optimum time to perform code review (junior devs need review early and often, senior devs are usually fine until later).