Introduction

Almost 10 years ago now I used to be a Java developer in Motorola. After a long hiatus in the embedded systems and a job change, I have come back to enterprise development, this time in .Net.

I remembered that in the good ol’ days it required 2 steps to see the final rendering of the XML documentation: firing javadoc (usually from within an ANT task) and the open up the content in a browser.

I was quite surprised to see that in the .Net area seeing the final output of the docs was not as straightforward as I hoped for. Yes, there was NDoc to parse the XML, but its development stopped around 2005 and it’s doesn’t support anything beyond C# 2.0. There’s also Sandcastle, but to make it work for me it has required a few downloads and a bit of tweaking here and there. And integrating it into my NAnt task had not been that easy either. But somehow in the end I have pulled that out.

Therefore I have been pleasantly surprised when I met CR Documentor, a little plug-in for visual studio that let’s you see your XML documentation as you write it. It’s almost like having a WYSIWYG editor, without having to launch Sandcastle, wait for the complete build, and open up the browser.

Installation

• Requirements:
  • Visual Studio 2005 or greater (I am pretty confident that you need at least a Professional version as opposed to Express). I am running it on Visual Studio Team System 2008, not sure whether it works also on 2010.
  • The DXCore plugin framework from DevExpress. Possibly the best (and only?) way to get it is to get through the excellent free CodeRush Xpress for C# and VB
• Download the plugin: CR Documentor is hosted at Google Code at this link.
• Copy the dll in your DX-Core plugin-folder (C:\Users\<username>\Documents\DevExpress\IDE Tools\Community\PlugIns)
• Restart Visual Studio

Usage

1. CR Documentor adds itself in the right click menu, close to the bottom. From the submenu, choose “Show CR_Documentor window”.
2. A new window opens up in floating mode (I prefer to dock-it to the right side together with my solution explorer and luckily the plug-in remembers this choice every time I open the window after closing it and at startup).
3. Now every time your cursor is on an XML doc, you can see the preview in the Documentor window. See for example when I put the cursor on the XML doc of a class: I get a complete picture of the documentation for that class and its methods all in real time.
   
4. There are a few other features that I don’t use very often. All of them are accessible by the right-click content sensitive menu:
   • Expand/Collapse all XML comments in the editor
   • Insert XML docs templates (I prefer to use GhostDoc for that).

Configuration

Like all DXCore plugins, you can access to the configuration by pressing ALT+CTRL+SHIFT+O combination. I like to check all my options to Sandcastle because that’s the tool that I will be using to create the final XML documentation.

Coding standards is one of those topics which can easily create endless discussions between developers (Steve McConnell prefers the term religious wars in his famous book Code Complete). Everybody seems to have his/her own preferences and pet peeves when it comes to the lay out of statements and naming of types and variables (not to mention the eternal “tab vs spaces” argument).

All the programming languages that I have worked with have their own guidelines when it comes to coding standards. Or have they? The C language, father of C++, C# and Java languages, has its own share of style variations: Emacs supports half a dozen C coding styles (K&R, BDS, Linux, etc…), and at least a couple C++ modes (Ellemtel, Stroustrup).

While the Java community can refer to a common standard, this doesn’t seem to be the case for C# developers. The guidelines from Philips (pdf) are the ones which one is most often redirected to, but one can hardly call them “official”; Microsoft has also something on the MSDN on naming conventions, but there doesn’t seem to be anything related to code layout (spacing, indentation, etc…).

Whatever the choice, though, only a few would argue that choosing one standard for the team and sticking to it is not of outmost importance to improve readability and ease maintenance for years to come.

Microsoft Style Cop

Enters Style Cop. Style Cop (not to be confused with Fx Cop) is a free Visual Studio plug-in which is released by Microsoft itself. It can be run on a single file or entire project or solutions and reports all the variations to its predefined set of rules for naming conventions, documentation and code layout. To run it on the current file, just right click on the editor and select the corresponding menu item:

This is the output that I got running the tool on the code above:

If you need additional information about how to fix a particular violation, you can right click on a StyleCop warning, select Show Error Help and dig in:

Default settings can be customized to some extent. To do so, right click on a Project from the Solution Explorer to invoke the settings editor:

From the Rules tab you can relax some of the rules or extend or restrict the scope according to the visibility (private/internal/protected/public).

Yes, you can remove the restriction on the Tabs if you want (but you don’t… do you?). You can even support Hungarian Notation if you wish so (God forbids…!!!).

Default settings are applied at a project level and saved in a file named Settings.SourceAnalysis; It might easily become tedious to repeat the same settings over and over (my Visual Studio solutions have typically at least 4 or 5 different projects, and not counting unit tests); luckily the settings are automatically applied to all projects located in the subdirectories of the directory where the file is. Therefore, it usually suffices to move the file in the solution directory; individual projects can ovverride the general settings by providing their own Setting.SourceAnalysis file if needed (I usually do that for the tests projects where I usually omit XML documentation for test fixtures).

On a final note, if you use MSBuild for integration then you can invoke StyleCop every time the solution is built. If you are interested, you can find all the details in this MSDN page.