Poor development activities section in CAL documentation

Dec 11, 2008 at 2:22 AM
I'm sorry for this negative title but I just had to provide this feedback.
I've been digging into CAL for the last couple of weeks. I really admire the general architecture and patterns. Obviously a great deal of thought had been put into this project. It's just a shame the development activities section provide so little guidance when it come to building your own app based on CAL. So here are few examples:
  1. While the how-to demonstrate using MVP the StockTrader app use mostly the presentation model. Why not provide an how-to for this pattern as well?
  2. There's not a word in the development activities about the controllers. One have to dig into StockTrader to get their role.
  3. The development activities section provide steps for registering a service but not for actually consuming one. Again one need to dig into StockTrader to figure out how is this done. Where should one locate the service interfaces? What is the purpose of a service class and when to use it?
  4. Same goes for the Models: where and how to use those? The development activities section provide no explanation...

And there are more... I emphasize the development activities section because I can't expect every developer in my team to read the full documentation and understand it. One expect the development activities section to provide a step by step guidelines of how to build and application based on CAL. Without it CAL is wasted because most developers would find it too time consuming to figure it all out. StockTrader is a beautiful and well written sample app but as it doesn't completely follow the development activities section it is sometimes more confusing than helpful.
I'm sorry about the rant. However, while the CAL team is busy converting it into Prism I this that the effort is not well directed. Prism is a nice idea (when I say Prism I mean the part that enable re-using code for WPF and Silverlight) but in the real world there will be (relatively) very few applications that will utilize it. CAL is a basic library which should be used with almost every WPF client (there are very few application in today enterprize environment which does not need to utilize a composite architecture).
 Thank you,

Dec 11, 2008 at 2:42 PM

When I first approached Prism, I was already familiar with all of the patterns that were being used. This is why I was initially attracted to it. MS didn't go out and "invent" new patterns or call existing patterns by new names. And I really appreciated that. As far as I can tell, Prism really is "guidance" at a certain point. I don't have to use MVP, MVVM, Controller, or any other pattern beyond a certain point. I would, though, because from personal experience, I like the flexibility and testability I get from these patterns. You seem to want MS to hold your hand and tell you how to build composite apps step-by-step. From what I gather, this is not what Prism is about. It's more about addressing the concerns one would have building a composite app, providing a minimal framework to enable it, and showing how various UI patterns can be used within its context. You may not appreciate this, but I applaud this team for approaching Prism the way they have done.

With that said, there is plenty of information out there about the patterns being used in Prism (to address your points 1,2, and 4). You should have no trouble finding out anything you need to know about any of the patterns the samples are using. You seem to want the Prism team to do all your work for you. You also seem to have an aversion to reading the code. Why? The code is valid documentation and is meant to be read as such. You and your team could easily sit down with the code/documentation and go through it in a couple of hours. BTW, the code/documentation is a step-by-step guide. I have used it to build two apps so far. Once you understand that Prism isn't trying to micro-manage your development process you will be much better off. And if your team is not willing to figure it out, then no amount of work the Prism team can do will fix that. 

Remember, everyone's "real world" is different. In mine, Prism will be used very often to build large-scale enterprise applications.


Dec 11, 2008 at 6:11 PM
Hi J.P. and thank you for your comments.
I'm too familiar with MVC, MVP, Composite, Dependency inversion and other patterns used by CAL. I have no problem digging through code (and in fact this is what I've been doing in the last couple of weeks) and I find StockTrader code well written and organized. I also fully understand that CAL is a guidance and eventually it's up to me to pick the patterns that best suit my application (which is also a large scale enterprize one :) ).

My point was that eventually we want to use CAL as springboard for rapid development. Learnability and simplicity being two of the stated design goals of the project. The development activities section is an important part in achieving that. However, this section misses some important points and does not completely match the StockTrader example structure. These are very specific points which are easy to take care of.
Thank you,
Dec 12, 2008 at 3:00 AM
Edited Dec 12, 2008 at 9:47 PM
Ken & J.P.,

This is a good discussion as we need feedback in order to improve the guidance. Ken can you prioritize this list of 4 items?  We should have some time to add new guidance for this release and I would like to understand what is the most important item for you. Also I would like to hear from others as well and know their priorities.

Blaine Wastell
Dec 12, 2008 at 4:19 AM
Hi Blain,
Thank you. I would say that my first priority would be number 3. I use CAL (and I guess many others) to present and update data from various sources in the enterprize. A sample app to demonstrate how to integrate CAL based app with WCF would be super great :). 2 & 4 would be the next ones (in that order) because they are not mentioned at all.
To communicate better my comments, I'll mention here, that the current state of CAL documentation and samples forced me to:
  1. Write a sample application of my own which include only one module and somewhat simplified (no MVP - just MVVM for example) but include full cycle (WCF client and server and EF data access).
  2. Based on the above sample, write a document specifying the steps to create a full cycle module.

The above will be handed to the development team so the developers will be able to repeat the steps and use the sample. As J.P. rightfully mentioned, CAL contains some choices and this is great. However, we should remember that development teams vary in terms of skills and knowledge. In just 3 years we switched from User Interface Application Block to Smart Client Software Factory and now CAL... Though each one serve a little different purpose they are in a way an improvement of each other in response to the changing landscape of software development (oops, sorry, I'm starting to ramble...). So to sum up learnability is a big factor when adopting a library/block/factory and I always like to think of KISS as the most important pattern...
Thank you,

Dec 16, 2008 at 4:09 AM
If I could chime in, I'd love to see a better explanation of how, and when, to use a Controller.  There are examples in the RI but its not obvious.  I get that its primarily for coordination between views or presenters (that is, plural) - but still not obvious how best to implement it.  I see a lot of opportunity to do it wrong and essentially void the benefit. 

Maybe more importantly, how to consume a real-world service, preferably ADO.Net Data Services.  And specifically how to connect a Model to the entities within the data service.  How to reference the data service when the actual entity classes are exported from the web services portion of the service.  Etc..

I love the CAL and working pretty hard to adopt it, but coming from MFC and light WinForms this is a pretty steep curve due to the many learnings needed -- of course the code is all there to read and grok but with the many layers of abstraction, inconsistencies between the RI and Quickstarts in terms of how MVC or MVP is implemented, where interface classes are stored, etc...tough without more explicit guidance. 

Please keep up the great work.....
Dec 16, 2008 at 5:32 PM
Hi Usna91,
I can't help you much with CAL (as I'm struggling with it myself) but as for the combination of entities and services you may try:
http://msdn.microsoft.com/en-us/magazine/cc700340.aspx and http://msdn.microsoft.com/en-us/magazine/dd263098.aspx.
Hope that it help,
Dec 16, 2008 at 8:38 PM
Thanks, Ken.  I actually subscribe to MSDN mag but hadn't (yet) read these.  Will definitely take a look...