Tag Archives: agility

Developping an app for the Windows Phone platform

For the last few months my colleague Charlotte and I have been working on a Windows Phone 7 app we hope to release soon. Attendants of our “Performance tuning and analysis during the Microsoft TechDays this week had a brief overview of this app.

In this post, I wanted to share with you all the tools we’re using to build this app.Most of them are free, so they might interest you…

Productivity / Code

Libraries

Source Control

Project Management

  • AgileZen (free for managing 1 single project)

Cloud computing

Web site

I personally love all those tools and libraries ! What do YOU use for your Windows Phone 7 development ?

 

Microsoft StyleCop vs Agility

When I write code, I try to keep it as clean as possible by following rules that I define and use in all my project. Those rules can be the ordering of elements within a class, or the way I choose name for my properties and methods…

Microsoft created a tool that analyzes C# source code in order to enforce a set of style and consistency rules : it’s StyleCop (available for free to download). StyleCop defines a lot of rules, for example:

  • Element must begin with an upper case letter
  • Field name must begin with a lower case letter
  • Prefix local calls with the “this” prefix

It is possible to enable or disable each rules separately, and this is what most users will do. Running StyleCop on one of your project can lead to thousands of warning. You can then choose which rules you want to keep enabled.

I started to use StyleCop the project I’m working on at job about one week ago. After disabling some of the rules I didn’t wanted to fix yet, I found a rules that was giving me a lot of warnings:

  • ALL elements must be documented

Hmm… This means that each single method or properties in my project must have a documentation… Well, if documentation is good lets start writing documentation everywhere. I though I will take a couple of classes per day, and write the entire documentation. I started with opening one of my class, and found this method:

?View Code CSHARP
1
2
3
4
5
public void OpenDocument(IDocument document)
{
// ...
 
}

StyleCop wasn’t happy because there wasn’t any documentation, so I wrote one:

?View Code CSHARP
1
2
3
4
5
6
7
8
/// <summary>
/// Open a document
/// </summary>
/// <param name="document">IDocument to open<param>
public void OpenDocument(IDocument document)
{
// ...
}

Then, I don’t know why but I asked myself “what the hell this documentation is going to help the user of the class ???”. Because one month earlier I went to the AgileTour (a french event about Agile methods), I remembered the Agile Manifesto:

  • Individuals and interactions over processes and tools
  • Working software over comprehensive documentation
  • Customer collaboration over contract negotiation
  • Responding to change over following a plan

I was thinking a couple of minutes, and then I decided to remove the StyleCop rules about documenting EVERYTHING in my code. I think that would be a waste of time and that would preventing me to put good comments where it’s really needed such explaning an algorithm or why I choose this way over this other way to do the job.

I’m still using StyleCop to have a set of rules about the style of my code. But for now, that’s it ! I think it is very important to make the differenciation between documentation and comments. If documentation is needed because it will generate a document outside the application then it might be usefull. But if the documentation is written just to have it, I prefer forget about it.