Archive for the 'guidelines' Category

Published by breki on 25 Sep 2010

Poor Man’s Task Tracking Tool, Revisited

Back in the days before Maperitive had been released for the first time, I wrote a post about how I use simple text files to keep the track of things I have to implement (and things already implemented).

It turns out the to-do list has grown so much that it is very difficult to decide which things to implement in which order. Some features or bugs come in the middle of implementing other features and I’ve frequently had to make use of SVN branches to be able to work things out.

So I got an idea of using Google Docs spreadsheets to create a list of tasks. But a simple list was not enough: I wanted the spreadsheet to be able to tell me which tasks should be implemented first and which can wait. I’ve added two columns to the list: priority and complexity. Then there’s a third column called score, which calculates a score based on the priority and complexity using a simple formula. The complexity is measured in “ideal hours” the task is supposed to take (a rough estimate, of course), while the priority is some value (usually an integer from 1 to 5) which denotes how important the task (or feature) is.

"to do" list using Google Docs

After entering tasks, I simply use spreadsheet’s “Sort sheet Z –> A” function to make the tasks with the highest score appear at the top of the list.

Simple, but effective.

Published by breki on 25 Apr 2010

Windows Services And Working Directories

A reminder for me: when developing Windows services, in the initialization code set the Environment.CurrentDirectory to the directory where your binaries are located:

string applicationFullPath = Assembly.GetExecutingAssembly().Location;
string applicationDirectory = Path.GetDirectoryName(
Path.GetFullPath(applicationFullPath));

log.InfoFormat(
"Setting the current directory to '{0}'...",
applicationDirectory);
Environment.CurrentDirectory = applicationDirectory;

This helps avoiding problems with .NET framework implicitly accessing various file resources stored together with your binaries. I had a situation where I wanted to validate an XML file using XSD schema files stored in my application directory. The code worked OK in the integration tests but failed when run inside a Windows service. It turns out .NET Framework’s XML validation code wanted to import certain dependent XSD schema files from the current directory, which is, in the case of Windows services, C:\Windows\System32 by default. Of course, the needed XSD files weren’t there, but the validation code doesn’t really tell you this, it just reports an unhelpful validation error.

Published by breki on 01 Mar 2010

The Delicate Dance Of Transience

H2O
Creative Commons License photo credit: Flowery Luza*

I’m in the final stages of polishing Maperitive before the first release. Well, not really polishing, I have a bunch of tasks yet to do, but I think I can see the light at the end of the tunnel.

As #I stated a while back#, one of the reasons I decided to do a major rewrite of the Kosmos code was to introduce inversion of control (IoC) into the architecture. Maperitive (ex-Kosmos) now heavily relies on Windsor Castle do to the wiring. I can say that investing in IoC (and sticking to SOLIDs) now starts to pay dividends: I can add new features with more ease and they tend to affect a relatively minor part of “old” code.

The problem with using IoC containers like Windsor Castle is when the components registered exceed a certain number that you can handle in your brain (Maperitive currently has about 130 components in IoC container). Then the whole thing gets a life of its own: even if you write extensive unit tests for individual parts, it gets more and more difficult to predict how the “organism” will behave as a whole.

When used in a Windows desktop application like Maperitive, the problem gets compounded by the intricate dependencies between different lifestyles of components. This is what I want to discuss in this post.

I’ll restrict the discussion to singletons and transients, since I only use these two types in Maperitive. I’ll give examples of components in terms of a mapping application (which Maperitive is), but I think it won’t be a problem to translate this to your own areas. I’ll start with the simple case of…

Singletons Depending On Singletons

This is the easy one: singletons are components which typically share the same lifespan as the application. A Map is a good example of a singleton: the user expects the map to be available at all times (after all, what would Google Earth look like without the map?). User typically uses a mouse to move around the map. And we luckily have only one mouse on our machines, so this is an example of another singleton (I’m a bit oversimplifying the stuff here, bear with me). So the Map subscribes to the Mouse events and this can be seen as singleton to singleton dependency.

These kind of dependencies are easy to handle, since the number of created objects is typically small and they all share the same lifespan. Also, singletons are (typically) created automatically by the IoC container at the start of the application so you don’t really need to explicitly create and destroy them yourself.

Transients Depending On Singletons

This is the second common relationship in a desktop application. You have a short-term task to do (usually as a response to user’s actions) and you create a transient object to do this task. One example would be a WebClient which downloads the map data from the server: once the download is done, you can kill the client (hmmm that sounds tempting).

Transients are typically created using factories. Windsor Castle offers a cool feature called TypedFactoryFacility which makes creating factories a lot easier (you don’t need to write the actual creation code, just specify your factory interface according to facility’s conventions).

A WebClient needs to know whether it has to provide credentials for the Web proxy. We can store this information in a Configuration object, which in our case is a singleton.

A transient component states its dependency on a singleton through constructor or property injection. Again, this scenario should be easy to handle, since the transient object has a shorter lifespan than the singleton it depends upon.

Transients Depending On Transients

This is where things can get messy. There are two possible scenarios when a transient object needs another transient object:

  1. They both share the same lifespan. Let’s say our WebClient wants to check if internet connection is up before sending a request to the download server. It can use a Ping service to ping google.com (it’s immoral, I know). Since both WebClient and Ping will be used for a short time, you can inject the Ping dependency in WebClient’s constructor. When WebClient dies, Ping should also die.
  2. The lifespans overlap, but are not the same.  Example: out WebClient has detected a communication problem with the download server and sends a notice to the user. The notice is displayed as a modeless dialog, which can stay on the screen until the user clicks on the Close button. So Notice is a transient object which does not die together with its creator, WebClient: once WebClient notifies the user, it is no longer needed. Notice, however, will live on until the user chooses to close it.

In the second case, having the Notice dependency in WebClient’s constructor or property is not an ideal option, for two reasons:

  1. It is not guaranteed the notice will even be used: if the download went OK, there is no need to notify the user. If your Notice component is expensive to create, this could be an issue.
  2. By using a constructor injection for a transient component, you are effectively claiming the ownership of this component. This conflicts with the fact that the component will live on even after your main component dies.

How do you solve this problem? My suggestion is to use factories – factories are usually singleton objects, so you end up with “transient depending on singleton” case. Even better: Windsor Castle’s TypedFactoryFacility also offers a mechanism to release components created with such factory.

The last (and most problematic) case is…

Singletons Depending On Transients

The problem with this is that your supposedly transient object will live the whole duration of the application lifetime. While in some cases this could be a valid scenario, in lot of cases it’s merely an oversight of the developer (especially when confronted with a huge number of components in a system).

Windsor Castle Inspector

The solution I used in Maperitive is to write a unit test which checks for singleton-to-transient relationships in my container and fails if it finds any:

[Test]
public void SingletonsShouldNotRelyOnTransients()
{
    IWindsorContainer container = Program.CreateWindsorContainer(false);
 
    WindsorContainerInspector inspector = new WindsorContainerInspector(
        container);
    IList<KeyValuePair<ComponentModel, ComponentModel>> dependencies 
         = inspector.FindDependencies(
        (a, b) =>
            {
                return (a.LifestyleType == LifestyleType.Singleton 
                    || a.LifestyleType == LifestyleType.Undefined)
                    && b.LifestyleType == LifestyleType.Transient;
            });
 
    Assert.AreEqual(0, dependencies.Count);
}

Of course, the condition for the test failure could be a bit modified to exclude any “special cases".

The code uses the WindsorContainerInspector, a little utility class I wrote to assist in inspecting the container:

public class WindsorContainerInspector
{
    public WindsorContainerInspector(IWindsorContainer container)
    {
        this.container = container;
    }
 
    public IList<KeyValuePair<ComponentModel, ComponentModel>> FindDependencies(
        Func<ComponentModel, ComponentModel, bool> dependencyPredicate)
    {
        List<KeyValuePair<ComponentModel, ComponentModel>> dependencies 
            = new List<KeyValuePair<ComponentModel, ComponentModel>>();
 
        foreach (GraphNode node in container.Kernel.GraphNodes)
        {
            ComponentModel dependingNode = (ComponentModel) node;
 
            foreach (GraphNode depender in node.Dependents)
            {
                ComponentModel dependerNode = (ComponentModel)depender;
 
                if (dependencyPredicate(dependingNode, dependerNode))
                    dependencies.Add(new KeyValuePair<ComponentModel, ComponentModel>(
                        dependingNode, 
                        dependerNode));
            }
        }
 
        return dependencies;
    }
 
    private readonly IWindsorContainer container;
}

Right now WindsorContainerInspector offers only one method: FindDependencies, which looks for dependencies based on the supplied predicate. I already have some additional ideas on what other possible problems to detect in the container, but I’lll write about this next time.

Published by breki on 05 Feb 2010

Poor Man’s Task Tracking Tool

31.01.
    - indicate the command prompt has focus
    - added detection of changed OSM files
    - implemented get-info command
    - started working on the error reporting func.
02.02.
    - implemented MailService
    - implemented AppDiagnostics
    - added error reporting form, but it still needs to be beautified
    - support for polygons/polylines consolidated from relations
04.02.
    - solved the problem: why is footway drawn ABOVE residential road?
        - it's because the footway feature is defined AFTER the residential road
    - fixed: bug with form disposing        
    - if a way is used in a relation, it should be ignored elsewhere
        -written tests for this        
05.02.        
    - TODO: the rules and features should be specified in the reverse order
        - from the most important to the least important
    - TODO: how to solve layering problem?
 
 
 
- TODO: beautify error reporting dialog
- TODO: find an icon for Maperitive
- TODO: implement multipolygon polyline rendering
    - TODO: write tests for multipolygon rendering

This is an excerpt from Maperitive’s Todo.txt file. I use it as a log of the stuff I did for the current day and also as a “database” of the tasks I still have do. On various projects during the years I used Trac, Bugzilla, on Kosmos I used ToDoList for a while, but nothing beats the simplicity of a text file.

The history log is a recent “invention”: since Maperitive is a pet-project, the time allocated to it is very unevenly distributed – sometimes I do a lot of work in a single day (usually on weekends without find weather or hangovers), but then I have to leave it untouched for several days. So often it happens that I forget what I was working on – and this history log helps me to quickly refresh the memory. Also, it’s a good psychological tool: I take a look and the log entries and see that some work has actually been done and I’m (slowly) progressing towards the first release.

The added benefit is that I can copy&paste these log entries into SVN commit comments. And of course, Todo.txt is kept under the source control like the rest of the code.

Published by breki on 09 Jun 2009

FxCop: How To Use It

Long Beach Harbor Patrol Say No Photography From a Public Sidewalk
Creative Commons License photo credit: Thomas Hawk

This is a second post on my “guidelines” series. Some information here is specific to the projects I’m working on, and some is more general and so applicable to any project.

FxCop is a free static source code analysis tool created by Microsoft. It analyses your built assemblies and reports any issues it encounters. It has a set of rules (which can be turned on/off) which it uses to detect these issues. FxCop comes both in the command-line form (FxCopCmd) and as a Windows GUI.

Building

The general approach in our build scripts is: the script compiles the code and then immediately runs the FxCop analysis. If it detects any issues, it automatically runs the GUI and opens the relevant FxCop project. NOTE: you need to press F5 key (rebuild project) in order for FxCop to show the latest results!

When run “headless” (on the build server), the script of course doesn’t open the GUI – it just simply fails and then kindly informs the offender via email.

Resolving Issues

There are basically three ways how to resolve issues detected by FxCop, described in the following subsections.

Fixing The Code

Fixing the code where the issue has been detected is the preferred approach.

Applying Suppression Attribute On The Code

SuppressMessageAttribute can be used to suppress reporting of a specific defect by FxCop:

[SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]

You can autogenerate these suppress lines by right-clicking on the issue, selecting Copy As -> Suppress Message. This will copy the suppress attribute into the clipboard and you can then paste it into the offending code. Depending on the type of the issue, the code has to be copied either in front of a class/interface, method, property or a field.

You should only suppress issues which you think

  1. aren’t really issues
  2. aren’t relevant
  3. the offending code has been designed on purpose.

On all other occasions, it is better to fix the code.

Excluding Issues In FxCop GUI

Sometimes (in rare situations) it is difficult to suppress an issue. In that case you can exclude them in the FxCop GUI by right clicking on the issue(s) and selecting Exclude.

NOTE: if you do any excluding in the GUI, don’t forget to save the FxCop project before exiting!

Language Issues

Since FxCop checks the spelling of class, method and other names in the source code, some FxCop issues are related to English dictionary. For example, on the latest project I’m working on, FxCop reported a spelling error for classes containing the MVC string, since MVC “word” isn’t in the standard English dictionary.

This can be resolved by adding such words in the CustomDictionary.xml file which is stored in the root directory of the project’s solution:

<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
  <Words>
    ...
    <Recognized>
      ...
      <Word>mvc</Word>
      ...
    </Recognized>
    ...
  </Words>
  ...
</Dictionary>

Adding FxCop Analysis On New VS Projects

When creating new projects in the solution, you have to do two things:

  1. Add the CODE_ANALYSIS compilation symbol in the project (using VisualStudio). Don’t forget to add it both for Debug and Release configurations. Without this symbol, FxCop will ignore any of your Suppress attributes in the code.
  2. Add the project to the FxCop project file, example:
<Target Name="$(ProjectDir)/MyTool/bin/MyTool.dll" Analyze="True" AnalyzeAllChildren="True" />

In general, I tend not to add FxCop analysis for unit test projects because unit test classes usually violate certain rules on purpose (or by design). One example is having test methods which don’t reference class instance stuff, for which FxCop reports the “mark member as static” issue.

Finally

There are some other minor “quirks” which can occur, I’ll try to add additional guidance if/when my team members encounter them :).

Published by breki on 08 Jun 2009

Gallio: Filter Attributes For Test Methods

There are three attributes which function as filters when running tests using any of the Gallio’s test runners:

  • Pending: tests which are in development and currently don’t run should be marked with the Pending attribute. This means the test runner will skip them when running the build script.
  • Ignore: this attribute is used for marking tests which are never to be run (they are kept in the code as a history). In general, it is a good practice to avoid such tests – you can get the history from your source control.
  • Explicit: tests marked with this attribute will only run when selected individually in the VS (Resharper, TestDriven.NET). They will not be run as part of the build script. Explicit tests are usually those which depend on a certain external system which cannot be guaranteed to be available at all times – we don’t want such tests to cause failures in our builds.

It is a good practice to supply these attributes with a string argument describing the reasons for marking the test.

UPDATE: Jeff Brown kindly provided some additional information about these attributes:

Tests marked [Ignored] and [Pending] will show as Warning annotations in the test report in addition to being skipped. In ReSharper they will also be shown with a yellow warning stripe to remind you that they are there and need to be looked at.

You can also add your own annotations to various code elements with the [Annotation] attribute.

This is my first article in the “guidelines” series I plan to write in the future. I want to maintain these guidelines separate from concrete project’s documentation since in the past I always had to copy this kind of stuff from one project’s wiki to another.