Visual Studio

Team System 2010: Static Code Analysis, easier to set rules

terje — Sun, 12 Jul 2009 16:41:01 GMT

In Visual Studio the settings for static analysis is done on the project property page, a tab called Code Analysis. You can set which code analysis rules you want to be active. The default in Visual Studio 2008 is to use all. If you run with this default setting you will generate a lot of "noise", since there are a large set of rules. You need to create a set containing the rules you and your team find are suitable for your organization and project. This set you have to apply to every C# project in your solution. In Visual Studio 2008 there is no easy way to do this. At Osiris we made an Addin to Visual Studio to ease this. We defined the set in a separate file, and used the Addin to apply that to all projects in a solution.

With Visual Studio 2010 this will be more easy, because in 2010 you can define sets of rules. It comes with a default list of sets. You can also define your own sets, based on any of the others.

To make your own rule set, just open any of the default ones, make any changes you like to it, and save it under a suitable name. A rule set file is created, which can be checked in together with the other files of the project. This file [rule set] can now be used by any other project you have. So you only need to define it once.

You still have to select it for all the projects in the solution, but this has been made easier by having solution properties, where Code Analysis is one of these setting pages:

It's then easy to select the rule set you want for all projects within your solution.

Mapping use cases to code

terje — Wed, 08 Jul 2009 19:30:24 GMT

There has always been a controversy between modeling and coding. All from the point where models are to be turned into code automatically, through the state where models are written and then forgotten after coding has started, to the point where one generates models from the code.

To me, code and model is representations of the same thing - the problem to be solved, or the solution to the problem. And when the solution matches the problem, which sometimes happens, all is well.

So the artifacts one make in a model IMHO it should be possible to map to code. I do believe that should be a strong guideline for which artifacts one uses in a model. If that holds, one can always reverse engineer a model from code, at least to a certain degree.

In order to make the picture more complete when one uses Use Cases for specifications is to add navigation diagrams to the suite. The term is coined by Manassis I think, and it shows how the different GUI pages are navigated. This takes form of a set of classes (one for each GUI page or independent part of a page) which depends on each other, where the dependency is named based on how you access the dependency. Ex.: “Button: Create New”. Although they say a use case diagram should be independent of the realization in form of GUI’s, I normally take a more pragmatic viewpoint, and connects these things together. One is to make a software program after all – not a theoretical thesis. I often connects a use case with a graphical page, or in some cases a page may encompass multiple use cases. Anyway, by using tracing from the use cases to the GUI pages, those relationships are taken care of, and a relationship matrix can show which use cases and which GUI’s are not connected, thus revealing missing specifications.

So, the use cases links to user interfaces (or messages for a message based system). Since the logic for the use case is not to be engraved into the user interface it has to be the Controller (or presenter or service component) that orchestrates the use case steps, hopefully most of it delegated down to the domain model. See Controller pattern within the GRASP patterns (Craig Larman).

Very often one uses the Use Case as the main work item for realizing a certain set of functionality, which encompass code on several layers, from the GUI layer, the controller layer, and on the domain layer, possibly also on the database layer. This duality, the use case both representing the code for the logic of the use case, and representing the whole work package for that behavior, is something I believe one just should accept, and not try to mitigate. It really poses no big problems, and mitigation of this would probably only cause over-complexity in the work item tracking or model.

Team System 2010 introduces the Layer Model, which can be used to enforce a more strict layering model in an application, making sure code is not placed inadvertently at the wrong layer, or crossing layer boundaries inappropriately. When one starts to take layering more seriously one also needs to be clear on which artifacts relates to which code-layer. The navigation diagram classes maps to GUI pages or GUI control classes. The Use cases maps to Controller classes. The domain model classes maps firstly to business class domain classes in code, and then, through some O/R mapping into a database model. Having a layering model, together with the necessary model elements, it should be possible to maintain a consistent relationship between model and code. One can then use whatever view one chooses and finds most convenient, and be sure that code and model is in sync. If the model then represents the specifications, the problem to be solved and the solution is also kept in sync.

Use Cases, User Stories and Scenarios - what are they - and how do they relate to TFS 2010

terje — Wed, 08 Jul 2009 12:07:09 GMT

All these three terms are used to describe the behavior of an application. They come from different process methodologies, and have different meanings, characteristics and are intended to be used differently.

Larry Guger also discuss these aspects and several others in his blog entries http://continuouslyintegrating.blogspot.com/2009/07/use-cases-and-visual-studio-2010-part-1.html and http://continuouslyintegrating.blogspot.com/2009/07/beginning-use-cases-identifying-actors.html.

The Use Case is the term used in UML and in the different Unified Process based methodologies. See http://en.wikipedia.org/wiki/Use_case for a good overall description. A use case is often looked upon as a more formal way of describing behavior, and which has to be accompanied by a detailed description following certain rules. However, a Use case can in fact be as light weight or as formal as one wants it to be. I find that this depends more on the process methodology one uses more than characteristics of the use case itself.

The User Story comes from the Scrum based processes, and is meant as a short concise way of capturing a users need for a certain behavior. See http://en.wikipedia.org/wiki/User_story for a useful description.

Scenarios comes as two different meanings, one is as a separate term used in agile modeling, see http://en.wikipedia.org/wiki/Scenario_(computing) for a description. It is very equal to a User Story, but I tend to see it as a more general term. The other meaning is as a certain path of actions for a use case. One talks of a "happy path" scenario, or an alternate scenario.

One can argue that a User Story can be converted into a Use Case, and there is a point in this. A Use Case is meant to describe an application behavior, whereas a User Story is used more freely to catch behavior "as is" from the product owner. This may lead to the case where multiple User Stories matches up to one Use Case, possibly as an Use Case with multiple scenarios, each scenario matching a User Story.

In the TFS 2010 these terms are used at different places in the suite. In the architect diagrams one can draw up a Use Case diagram, and in the Work Item store you can create User Stories. You can even create a User Story item from the Use Case artifact in the Use Case diagram. So these items can be related in TFS 2010. However, since they are not coming from the same methodologies, the mixing of these can be confusing.

I’m very pragmatic (even if I’m a theoretical guy), and I’ve noticed people have problems with these terms. I often just say that it’s more important to catch the behavior aspect of the requirements, regardless of whether you call it Use Case, User Story or Scenario. Scott Ambler has an interesting article on Agile Maturity (http://www.ibm.com/developerworks/blogs/page/ambler?entry=apmm_overview). I’ve noticed the same thing, that dependent upon the maturity of the product owners, the developers (really all involved), one uses the process differently. Also, dependent upon the size of the project, the maturity of the organization, the clarity of what is to be developed, and who’s the client and how is the contract specified, the need for formalized specifications vary based on these factors. A use case specification is more formal, than a set of user stories. Although as you so nicely shows, use stories can be converted into use cases. I fully agree. But I feel there is a one-to-many relationship between use case and user story. And then I’m not quite sure if I want that within the TFS's work item system. It just becomes too much.

I tend to take a pragmatic approach to things like this, and just say that you could argue that these terms are "equal enough" to be used interchangeably. In a real setting I would tend to try to catch as much as possible from a client (product owner) in terms of user stories, and during analysis convert these to Use Cases. After having made my set of use cases, and made sure I had captured enough to start working with code, I would convert these into work items to start the show. In order to make the terms less confusing, I would rename the User Story work item types into Use Case work item types. No other changes really required. And then I would simply use the actual User Stories as yellow notes in a customer meetings.

It is said that a Use Case need a more thorough specification, detailing the action steps it should take. One thing I’ve started to recognize is that a set of test cases is very similar to a set of use case action steps, and should never be less than these steps. So, to save on work to be done, one could simply skip the action steps, and just use the test cases with their steps as the specification. It might be that the Microsoft guys have been thinking in this route when they connected the User Story so directly with the Test Cases. It makes sense, and gives a leaner specification. But, it makes the User Story look even more like a Use Case.

Hiding generated code from Code Analysis, Metrics and Test Coverage

terje — Mon, 10 Nov 2008 09:09:41 GMT

When I do either Code Analysis, Code Metrics or looking at Code Coverage results, I don't want to have any generated code affecting the results. It just confuses the numbers, and I do not really care how generated code looks - it should just be invisible.

Generated code appears several places, code is generated by any of the multitude of wizards and designers in Visual Studio, or it may be generated by a 3rd part tool or generated by a self-written tool.

There exist an attribute which, if attached to the class or method, is intended to hide the code from these analyses. However, it fails to do so for the Code Coverage. The attribute is the GeneratedCodeAttribute, and it is intended to be used for any tools generated code. See http://blogs.msdn.com/fxcop/archive/2007/04/27/correct-usage-of-the-compilergeneratedattribute-and-the-generatedcodeattribute.aspx for more information on the correct usage. It can be used both at class level and method level.

However, the Code Coverage doesn't abide by these rules, as also reported in a two bug reports http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=338895 and http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=349243. The latter indicate they will not fix this bug, so please go in a vote for a fix!

As a workaround there are two more attributes which can be used, the DebuggerNonUserCode and DebuggerHidden attributes. The former is a combination of the latter and the DebuggerStepThrough attribute. The DebuggerNonUserCode attribute can be used on both class and method level.

By using this attribute in addition on generated code, it will not show up in the Code Coverage either.

The table below summarizes this:

	GeneratedCodeAttribute	DebuggerNonUserCode DebuggerHidden
Code Metrics	Excludes code	No Effect
Code Analysis	Excludes code	No Effect
Code Coverage	No Effect	Excludes code

Further, Microsoft seems to have "forgotten" to add these attributes to some of their own generated code, among them is the Winform generated code. The MSDataSetGenerator adds the GeneratedCode attrbute, but not the DebuggerNonUserCode attribute. (If the Code Coverage had abided by the rules, this would not have been a problem)

For Winform generated code, it is safe to add these attributes afterwards. The generated file will not be rewritten, just changed, when you add more or edit the controls. Just add them as shown below:

        [DebuggerNonUserCode]
        [GeneratedCode("Winform Designer","VS2008 SP1")]
        private void InitializeComponent()

The MSDataSetGenerator is not so forgiving, since the file easily can be rewritten. However, all the classes are partial, so by adding another manual file, and using the attributes there, most of the DataSet can be removed from the Code Coverage. Adding one dataset with one table generates a lot of classes, the code below shows what is needed to eliminate a dataset and its tableadapter for a table named ErrorLog.

namespace WindowsFormsApplication10

    [DebuggerNonUserCode]

    public partial class DataSet1

        [DebuggerNonUserCode]

        public partial class ErrorLogDataTable

        [DebuggerNonUserCode]

        public partial class ErrorLogRow

    namespace DataSet1TableAdapters

        [DebuggerNonUserCode]

        public partial class ErrorLogTableAdapter

        [DebuggerNonUserCode]

        public partial class TableAdapterManager

In my little test case, code coverage changed from 2,54% to 10% just by removing the DataSet1 alone.

Under the Properties folder (for a WinForm app), the Resources class is decorated with both attributes (Hurrah!) (luckily since it's not partial....) whereas the Settings class only have the GeneratedCode attribute. (Why are these two different ?). The Settings.Designer.cs file is regenerated each time you change anything in the settings designer, but it is partial, so the same trick as above with the DataSet can be used - create a new file, with the same partial class declaration, and add the DebuggerNonUserCode to it.

In a later post I'll try to make an even more comprehensive list of which generators work and which doesn't, in this respect, and outline the workarounds for these.

Hopefully - all of these will be fixed in Visual Studio 2010.

Article on Subsystem branching

terje — Sun, 02 Nov 2008 12:38:26 GMT

I did an article on Subsystem branching (http://geekswithblogs.net/terje/archive/2008/11/02/handling-subsystem-branching.aspx) as a result of a post on the Microsoft forums regarding this.

Further, at the PDC 2008 conference now, Grant Holliday made me aware of the TFS Dependency Replicator, which also is a way to solve the problem. It corresponds to the solution I named Solution 3B, however, it's not using the branch/merge facilities, so the TFS itself is not "aware" of the file copied. Anyway, a great tool !

The article is as follows:

This article came out of a post on the Microsoft forums concerning how to handle team builds of subsystems. The post can be found here, look up the original post to see the problem in detail. Some of the problems the original poster got, concerned build reports which included work items belonging to other subprojects, but the problem go further than that. By not having a proper structure for your source code, you run the risk of build problems when you try to set up team build.

The problem concerns how to arrange your source code and build structure in these cases. There are several options, as outlined below. Which one to choose depends on your particular situation.

In the original problem, each subsystem resided in separate team projects. For this discussion, the subssystem may or may not be located separately.

For the sake of the discussion: Assume the existence of a Common framework project, and two other projects named Project1 and Project2 which uses this common framework. You want to build these as separate build projects, so to get as high isolation between them as possible.

There is guidelines for this on codeplex, see http://www.codeplex.com/TFSGuide/Release/ProjectReleases.aspx?ReleaseId=6280 but I feel the guidelines there on source code structure is somewhat lacking, although not in any way wrong, but I would like to add from my own experience, take this for what is it - good intentions .

A) A decision to use one or multiple TFS Projects should be based on other criteria, like teams, rights management, etc, and not on the problem you have.

B) The reason you get the behavior you describe first, is that both your builds "points", so to speak, at the level above your projects, that is the node called 'source'. It is this that determines what is shown in the build report. And no, you should not change anything in the build report. At this level, you probably have two solutions, one called Project1 and one called Project2, or if you have the solutions down at the level of the Project1 and Project2, you have still your workspace for the build at the level of the 'source'.
So in order to get the behavior you want, you have some options. Which to choose depends a bit on the size of your projects, including common, and the stability of the 'common' framework, your team sizes, how much isolation between them you want etc etc.
I'll outline these options below:

Solution 1: Multiple build workspacemappings

Choose this if:
Your projects are small,
common is small,
your teams are small,
or the same team works on all projects including common,
and/or 'common' is not very stable, meaning it's as likely to change as your projects.

Setup:
Keep your source structure exactly as you have outlined.
Move (if they are not already there, by default they should) your solution files (sln) down to each project, this is essential.
Use project references between each project and common, exactly as you have outlines. Ignore the warning from Visual Studio you may get above referring above your root. You know what you're doing.
Now the change from what you have today:
In the workspacemapping of your build (See Edit Build, 'Workspace'), make -2- mappings, one goes to Project1, and the other goes to Common.
Do the same for Project2.
If you now change something in Project1, and on that checkin associates this with a workitem,both the workitem and the changeset will only show up in the build report for Project1, and nothing will show in the build report for Project2.

Advantages: Simple to do
Disadvantages: A developer may not always get the latest source down, if they are unaware of the dependency on Common. If Common is a very long path-way away from your project, more levels than what you have shown above, this problem is much more likely to happen, in that case got to solution 2 or 3.

Solution 2. Source code branching:

Choose this if:
Your projects are a bit larger,
a separate team is or has been working with Common
you need isolation between projects, meaning Project2 will not be bothered by requests from Project1 to change something in Common.
You have a more complex source code structure.

Setup:
Change your source code structure below Project1 and Project2 to include a branch FROM Common. that is, make it look like:

Source
     Common
     Project1
         CommonBranched
     Project2
         CommonBranched
Then of course create the branches from Common to the two respective CommonBranched.
It is probably wise in this setup to have a separate solution for Common alone, and its own CI build to make sure it is correct before merging changes over to the Branches.
The solutions for Project1 and Project2 should be as described in solution 1, no changes there.
Note that one would normally not do any changes in the source in the CommonBranches, one could of course, but that would create a merging issue later when one merges new or updated code from the Common trunk.
Advantages:
Provides better separation between the projects and common
A developer will always get a buildable solution if he takes get latest from the Project node.
Disadvantages:
Every change in Common must be merged over to the branches. This will give an extra step in the process. For a small 'enterprise' this overhead may not be justified, for a lager one, it may be an advantage - due to the fact that this provides isolation and awareness of changes.
Possible changes to the branched source could make them non-mergeable at a later time.

Solution 3: Binary deployment branching:

Choose this if:
You have (a/many) large project(s)
Your common framework is rather stable,
Your common framework is used in many other projects, and you would not take the risk that someone at those projects made changes to the source that would make them non-mergeable at a later time.

Setup:
Change the source code structure as follows:
Source
    Common
           Deploy
    Project1
           CommonBranched (or Libs or References)
    Project2
           CommonBranched (or Libs or References)
In addition to the CI build for Common, you should make what I would call a public build, which you build every time you want a new "release". This build should have an extra step, f.e. using the AfterEndToEndIteration target, that it should check in the resulting 'dll' and 'pdb' file into the Deploy folder. (Use the ***NO_CI*** trick on that checkin to avoid triggering the CI build again.) This build btw, should not be triggered nor scheduled. You trigger this build manually whenever you need a new release of the Common library.
Now, when that is done, branch the Deploy folders, which mean that you in fact branch the binaries, into the CommonBranched folders.
Advantages:
The teams working on Project1 and Project2 can't mess up the source code. IF they want a change they must post a workitem to the Common team, and wait for a new release. . This is a good thing !
Good isolation (as in Solution 2), and the framework is very nicely controlled, but in addition, no possibility for a source code problem with the Common source code branched into the projects.

Disadvantages:
The build scripts must be modified
Binaries must be checked in (not a problem IMHO).

Versioning should be introduced in the build process (not described in this post), may further complicate the build script

Advantage in disadvantage:
When the build script changes have been done, the process is smooooottth .

Solution 3B : Binary deployment with immediate merge

This is similar to solution 3 above, except that instead of doing a manual merge operation, you let the build system perform this for you. This will effectively chain the system builds. If Common is built, all other projects that depends on this will also be build. The advantage of this approach is that if you have a large total system, a change in any of the upper level projects will be faster to build, since the lower levels already have been built.

Regardless of which solution above you prefer to implement, your problem with workitems will be solved. All three solutions will provide the necessary isolation.