Vishful thinking…

Guidelines for writing a good UserStory

Posted in Agile, Scrum by viswaug on September 26, 2007

We have been using Scrum to manage our projects for almost the past five months now. It has been working great for us so far and has helped boost team work and increased the morale of the entire development team. I think it has enabled the team to keep their eyes on the ball and keep making progress by avoiding unnecessary distractions. One thing I have been struggling with in the Sprint planning meeting are with writing the UserStories. I am finding it tricky to come up with good clearly defined UserStories from the discussions we have been having. The INVEST acronym from the “User Stories Applied” book by Mike Cohn I think should serve as a good guideline for defining UserStories. The following is from Doug Seven‘s take on INVEST.

INVEST stands for Independent, Negotiable, Valuable, Estimatable, Small and Testable.

  • Independent
    The story should not carry with it dependencies, which can lead to estimating problems. Instead the story should be completely independent so that it can be worked on without pulling in a set of other stories.
  • Negotiable
    Stories should have room to negotiate – they are a starting point, not a contract.
  • Valuable
    The story should communicate the value to a user or customer, not to the developer. The story should define not only what a user can do, but what value the user gets from the implemented story. If there is no value, cut the story.
  • Estimateable
    You need to be able to estimate the amount of work required to implement the story. If it is too big and too daunting (an epic), break it up into smaller stories.
  • Small
    Similar to the previous, stories need to be small. Large stories are too complex to manage, and are typically more than one story compounded together.
  • Testable
    The implementation of the story needs to be testable. Define the tests that can be performed to validate the story was correctly implemented.

Interesting read on catching Exceptions

Posted in Uncategorized by viswaug on September 26, 2007

This article explains why catching exceptions as the base ‘Exception’ is always a bad idea. I have to confess that I have that mistake before. I agree with the author in his ideas that exceptions should not be caught unless you know what kind of exceptions you are dealing with. But it does kind of get real hard to implement in most cases because most third party libraries do not do a real good job of documenting the exceptions that they will be throwing internally. So, given the fact that you are working with a black box of exceptions you are almost forced to catch the base Exception if you don’t want your customers thinking that your application was the origin of the crash. Anyway my 2 cents on the issue… But the article is a real darn good read.

Reflection OR Introspection

Posted in Uncategorized by viswaug on September 26, 2007

In my last post I had mentioned the Common Compiler Infrastructure (CCI) being used in the MRefBuilder, I thought I would elaborate on it a little bit in this post. Most .NET developers are aware of Reflection and its API. Reflection is a very expensive operation and should be avoided when possible. Also reflection data should be cached whenever possible. I recently came across another way of getting to access the Type information inside an assembly ‘Introspection‘. This is relatively new technology which gives you access to the assembly metadata like Reflection only without the Dynamic Methods Invocation. In other words, it gives us a read only access to assemblies. So, that eliminates its use in places where Dynamic Method Invocation is required.

The Introspection APIs are not available as a part of the standard .NET Base Class Libraries but can be found in the ‘Microsoft.Cci.dll’ assembly available with FxCop. FxCop uses Introspection to access the assembly metadata in order to perform its code analysis. The advantages of Introspection over Reflection are that it does not lock the assemblies and it supports multi-thread access. If you are curious like me, download this presentation to engage your curiosity.

Documentation using Sandcastle – Part 1

Posted in Uncategorized by viswaug on September 26, 2007

I recently successfully created the code documentation for our projects using Sandcastle. Sandcastle is a documentation compiler for managed class libraries. It helps generate documentation for your .NET projects in a familiar MSDN format. Sandcastle can be configured to generate documentation in different styles. I created our documentation in the VS2005 format and couldn’t find too much help in creating help in custom styles. Sandcastle does ship with a couple of other documentation styles like ‘prototype’ and ‘hana’. Sandcastle is still in CTP and has not yet moved to RTM yet. So, the documentation is still mostly missing thus making it harder to customize using Sandcastle in your build process.

The compilation of the documentation in Sandcastle happens in a series of steps chained together to produce the desired end result. The figure shown below sheds more light into the steps that are involved in the process.


 Sandcastle uses three separate tools to achieve its end goal. The three tools used by Sandcastle are

  • MrefBuilder
  • XslTransform
  • BuildAssembler

 All three executables can be found in the “ProductionTools” folder under the Sandcastle installation path. A new user environment variable called ‘DXROOT’ will be added to your machine after the Sandcastle installation. So if you don’t know where Sandcastle is installed just execue ‘echo %DXROOT%’ at the command prompt. The function of the aforementioned tools are as follows

MRefBuilder – This executable uses CCI (Common Compiler Infrastructure) to generate reflection metadata in a XML format for the specified DLLs. In other words, it outputs a file containing information in XML format on all the Types in the assembly. The schema of the generated file is quite complicated but it is essentially a list of ‘api’ elements.


        <api id=”cer” />

                <!– many child elements containing reflection data on cer –>


<!– more api elements –>



XslTransform – This executable applies XSL transformations to XML files. This is a general purpose utility that takes in a XSL file and a XML file and produces an output file which is the result of applying the supplied XSL file transformations to the supplied XML file.

BuildAssembler – This executable is the core engine behind Sandcastle. It collates information from the comment files generated by the .NET compiler and the reflection information files from MRefBuilder and XslTransform into a set of HTML pages. BuildAssembler controls the component stack at the center of Sandcastle. The component stack that will be executed by the BuildAssembler should be passed in to it as a configuration file argument. The configuration file ‘sandcastle.config’ used for the VS2005 style documentation can be found in the ‘Presentation\vs2005\configuration’ folder under the Sandcastle installation path.

More to come …