Use this to start structuring the design of the product.
First pass, I'm anticipating the following components:
- Client Frameworks Provide containers for the main UI UserControl
- Iteration 1 Windows Forms Application (Stand-alone Client)
- Iteration 2 VSTS Addin (IDE Client)
- Backlog Console Application (think "tf changeset XXX")
- Backlog Web Forms Application (why not? ;)- how about webpart instead (from MR) )
- .NET Class Library containing UserControl...
- Iteration 1 ...and associated host-agnostic UI code. Used to display for 1.1 - 1.3
- .NET Class Library containing logic for:
- Iteration 1 Providing the available versioned items
- Iteration 1 Providing the changeset history of a versioned item
- Iteration 2 Providing the branch history of a versioned item
- Iteration 2 Providing the work items associated with a versioned item.
- Backlog Providing the labels, comments, etc for versions of a versioned item
- Backlog Providing an interface into other source control functionality (View changeset, compare, edit comment, view label, etc)
- Backlog Listing shelvesets containing the versioned item (and the version it comes from)
- .NET Class Library (nUnit or Ms Unit Test) testing the logic layer...
- Iteration 1 ...in terms of a Mock Source Provider (light layer of abstraction over the TF object model)
Assembly Dependence Map Public Key for Assemblies
| Namespace || Library || Purpose |
| CodePlex.Vertigo || CodePlex.Vertigo.dll || Vertigo Primary Logic and Control |
| CodePlex.Vertigo.Common || CodePlex.Vertigo.dll || Constants, Enumerators, Base Exceptions |
| CodePlex.Vertigo.Data || CodePlex.Vertigo.dll || Datasets, Data Objects |
| CodePlex.Vertigo.TeamFoundation || CodePlex.Vertigo.dll || Primary Team Foundation Integration Logic |
| CodePlex.Vertigo.TeamFoundation.VersionControl || CodePlex.Vertigo.dll || Primary access to VC |
| CodePlex.Vertigo.TeamFoundation.WorkItems || CodePlex.Vertigo.dll || Primary access to WIT |
| CodePlex.Vertigo.UI || CodePlex.Vertigo.UI.dll || Vertigo Classes for MVP structure (View Interfaces and Presenters) |
| CodePlex.Vertigo.UI.Controls || CodePlex.Vertigo.UI.Controls.dll || Core user controls |
| CodePlex.Vertigo.VisualStudio || CodePlex.Vertigo.VisualStudio.dll || Visual Studio Integration |
| CodePlex.Vertigo.Tests || CodePlex.Vertigo.Tests.dll || Test library for CodePlex.Vertigo |
| CodePlex.Vertigo.Tests.UnitTestLibrary || CodePlex.Vertigo.Tests.dll || Unit test base classes, mock classes, factories etc. |
| CodePlex.Vertigo.Client || vtree.exe || Command line and Windows Wrappers |
| MindFusion.** || MindFusion.** || Third Party Diagramming Tool |
Michael asked me to change this discussion to a new page.
So here it is Layout Design
Constraints & "little" decisions
Coding Standard Options
- "FxCop guidelines and what Ctrl-K,Ctrl-D does in Visual Studio"
- Phillips Medical
Notes and discussion of changes
Eric ->Unless Steve REALLY REALLY REALLY wants vb.net :)Steve ->
C# is ok with me as long as the plan gives me 50% more time to get my stuff done due to casing and bracing issues. :-oMichael ->
You mean you want an extra 50% more time to actually program correctly? :-p Eric ->
It's just the absence of poetic license :)Heynemann ->
I really think that for coding standards we should relly on FXCop which is a great tool, but for Design Guidelines, what better than the .Net Framework itself. The book that contains the design guidelines that were used for Frameworks 1.0, 1.1 and 2.0 is called Framework Design Guidelines by Krzystof Cwalina and Brad Abrams and published by Addison-Wesley. Great book, worth it´s value about ten times. And as for namespaces we can´t just be "*.dll"-like. It has to be planned. Most common usage scenarios in main namespaces and less-used scenarios in subnamespaces. We can create a discussion about that in the forums.Eric ->
The Phillips standard is pretty straightforwards, and it's really just that somebody took the time to write the long version of "FxCop guidelines and what Ctrl-K,Ctrl-D does in Visual Studio" Maybe we should just use that instead :) As an aside, has anybody else watched the video series Designing .NET Class Libraries? It's long, but it's got a LOT of good stuff in there, probably some overlap with Abram's book since he was involved.
As for the "*.dll" like, we typically use subnamespaces to capture "subdomains" of the tool in the same manner as the individual providers in the ADO.NET world. We generally bundle one namespace per assembly (aka one namespace per project file) unless there's an emergant need to do it another way. This would lead to the suggestions above - I really don't like "VersionQuery" for the logic lib, so suggest away! If we want more detailed breakdowns, we can do so, but we've found it's best to start simply and allow the deployment view to emerge concurrantly to the class and object models.
Keep it going!Heynemann ->
Added the Exceptions subnamespace to the CodePlex.Vertigo.VersionQuery namespace. If anyone thinks we should leave the exceptions in the same namespace just change it here and let me know. But I think that since the exceptions aren't used in the main scenarios by the user of the VersionQuery namespace (the win.forms app and later the Visual Studio Addin) we should leave them in a subnamespace.Eric->
I'm not sure about this scenario for a couple reasons... First, I'm not sure how many exceptions we'll actually have. I'm not initially seeing the need for many. Second, those we DO have will probably need to be communicated to the UI elements pretty directly - things like "Couldn't log into server", "Item doesn't exist", etc.MR ->
At first I agreed with the subnamespace but when I thought about the .Net framework and then double checked I cannot find a single instance with an exception subnamespace.Heynemann ->
I know that the .Net Framework doesn´t have it, but it doesn´t because exceptions were initially meant to be used by developers (which turned out to be a bad design after all), so that´s why they are in the same namespaces as the classes they actually refer to. But our exceptions shouldn´t be used for flow control. In fact "Couldn´t Log Into Server" and "Item doesn´t exist" shouldn´t be exceptions at all, since they are regular flow of the application. You shouldn´t use exceptions to situations you can predict. We should implement a method like TryConnect(serverUrl) that returns null if the server is not available and not a Connect(serverUrl) that throws an exception if the server is not there... But if the server is available, but it does behave in some way we don´t expect, now we should have an exception, which is a situation we didn´t foresee. Well, at least that´s what best practices state. It states that exceptions are way too expensive for you to use them as runtime flow control.Eric ->
I extracted the visual studio integration namespace into its own .dll because we'd otherwise have a circular dependency between the controls used to display and the core vertigo dll. (Thought Occurs
) However, I may be misunderstanding the balance of responsibility here: I'm personally envisioning a design where the central UserControl is also the host of the required display logic to access the CodePlex.Vertigo namespace and query for the info related to its current versioned item. The way I've seen things drawn, I'm wondering if you guys are envisioning the various hosts as serving as the Controller, getting the data from CP.Vertigo and pushing it into the controls. I guess we're really discussing if we're doing MVC or MVC II.MR ->
Yes, you are correct in that I am seeing it from the other side not using MVC but MVP (or MVC II) if you will. Here is a good description of Model-View-Presenter from Martin Fowler
which I think many call MVC II (especially in the Java, Struts world). I did intend for the controls to be the view area and to be as dumb and thin as possible with the presenter pushing information to the view. Also I had originally left the Visual Studio section out as a seperate .dll as well but for the same reasons put it back into the core for concern over circular dependency based on pushing to the View and how the DTE II environment works in hooking into Visual Studio. We may end up with a CodePlex.Vertigo.VisualStudio.dll. I think it can go either way. Let's leave it as a seperate .dll for now and we'll update the dependency map. In fact this brings us to a new point in the design. Eric-- based on the MVP model and also your note on the Assembly Dependence Map
(in which you are exactly correct- why would vtree have a dependency on the core under our plan?) will you create a new dependency map. Then I'm going to add a task to roughly stub out the MVP classes and interfaces for the stand alone rich client so that tests can be written on them (or don't stub them and just start the tests). I'm going to do the same from the TFSOM API side.Eric ->
(MVC) I looked at fowler's MVP post, but I think there's still a little bit of cross-talk going on here. I'm going to copy your post to an MVC Discussion
page and elaborate there.Eric ->
(Dependency Map) I'll be happy to take care of this, but I won't get to it until Monday since I'm heading out for the weekend. I'll assign myself a task for it, and if anybody else wants it before then you can steal it :)Eric ->
Updated the dependency map - see commentary there.Steve ->
PROPOSAL: I was looking over the namespaces and the dependency map and thought a little more clarification to the namespaces might be appropriate. At first, I didn't immediately see the tiers in the dependency map. I think that we may want to add UI
to the three UI level namespaces and Middleware
to the Codeplex.Vertigo namespace. We may want to go so far as to add Data
to the TeamFoundation namespaces, or maybe tack on Adapter
? I haven't made any changes to the diagram yet, I wanted to open this up for discussion first.Eric ->
I think I'd rather do this with swimlanes on the diagram or additional notations rather than modifying our namespaces. Overall, I think the names we have seem to fit pretty well with what we'll need.MR ->
On a valid point from Bernardo (heynemann) we were missing an assembly that represent the UI under the MVP model. He has added this. The Controls dll could arguably be moved under the same assembly as the UI but I think these are better left seperate since controls can and should evolve seperately from the MVP UI assembly. But the namesapce for Controls should fall under .UI. I will add this as a work item for action.