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.

One of the (many) useful features of Visual Studio is the Implement Interface. With it, if you declare a class as implementing a particular interface, you can have Visual Studio generate stubs for all the methods declared by that interface.

With default settings, Visual Studio will place regions around the stubs that it just generated:

As you may know from previous posts, I am not a fan of using regions within C# code. I tend to favor lean classes and short methods, I find regions almost useless; worse, they tend to visually clutter the code.

Luckily, there’s a way to configure Visual Studio not to put regions around implemented interfaces. It’s buried under Tools->Options->Text Editor->C#->Advanced. Simply uncheck the “Surround generated code with #region” in the “Implement interface” group:

Voilà. You now have all your stubs ready to be implemented, without those annoying regions around:

I love shortcuts. I really do. So with some excitement I have found a few in the Visual Studio Editor that may come handy once in a while. These are the shortcuts to transpose characters, words and lines:

Transposing Characters (CTRL+T)

This is mostly useful if you mispelled a word. Since most code typing is done with Intellisense, I have found this useful for comments mostly.

Transposing Words (CTRL + SHIFT + T)

Beside the occasional typo writing comments, this is handy when after refactoring a function signature I have changed the order of the parameters.
Suppose you have for example you call a function in the following way:

calculateVat(price, percentage)

if for whatever reason calculateVat signature has changed so that the percentage comes first, you just need to put the cursor on price or between the two words and pressing CTRL + SHIFT + T you’ll have the following:

calculateVat(percentage, price)

Transposing lines (ALT + SHIFT + T)

I use the following formatting to wrap long function signauters across more lines:

public void AddEmployee(
    string name,
    string surname,
    string address,
    string homePhone,
    string mobilePhone,
    string email)
{
   // implementation here
}

Suppose that I decide that I want to reorder the parameters such that the mobilePhone comes before than homePhone, for whichever reason. I just need to place the cursor somewhere on the line of “homePhone” and the two lines will swap. To remember which is the direction of swapping, my mnemonic is that the line where the cursor is will fall.

public void AddEmployee(
    string name,
    string surname,
    string address,
    string mobilePhone, // this line has moved up
    string homePhone,  // this line has moved down
    string email)
{
   // implementation here
}

This is especially useful if you have more overloads of the same function where you need to update the order of the parameters in each of them. It’s certainly quicker than a copy&paste tecnhique.

If you need to move one line of more than one position down, just keep pressing the ALT + SHIFT + T combination and the line will keep falling down (the cursor automatically stays in the line that is moving).

(zdwfg7nay2)

Design by Contract was first introduced by Bertrand Meyer, creator of the Eiffel programming language,  in his seminal book Object-oriented Software Construction. In a nutshell, DBC is based on the following principles:

• preconditions: a method imposes on the client a set of conditions that must be met in order for the method to be invoked successfully (think about parameters validation).
• postconditions: a set of properties are guaranteed by the method immediately after the execution (think about a return value that can only be positive, for example).
• invariants: a set of properties on the class are assumed to hold before the method starts and are guaranteed to hold after the method completes (think about a field of the class that may not be negative, for example).

A contract formalizes these three things. How can contracts, and defensive programming in general, help us developing better software? Bertrand Meyer explains it in this interview from 2003:

The main purpose of contracts is to help us build better software by organizing the communication between software elements through specifying, as precisely as possible, the mutual obligations and benefits that are involved in those communications. [...] relying on these notions—that is to say, making sure when you write software that don’t just write the implementation, but also write the more abstract properties underlying the implementation in the form of contracts—provides a greatly added software development experience in several respects. It helps ensure correctness in the first place, helps debugging, helps testing, helps ensure inheritance is properly handled, helps managers, provides a quite effective form of documentation, and a few others.

Up to now, only a few languages supported DBC natively, and C# was not one of those. With .NET 4.0 Microsoft fills this gap with Code Contracts. It’s possible to download Code Contracts for Visual Studio 2008 for the Standard Edition and the Team System edition.

A Basic Example

Let’s see a basic example of how one can use Contracts in a simple class. (to try this on your own you need to install Code Contracts from msdn web site). In this case I have a class with a static method that simply inverts the content of a string (the choice of the algorithm here is irrelevant).

using System;
using System.Diagnostics.Contracts;

namespace TestContracts
{
  public class StringInverter
  {
    public static string Invert(string s)
    {
      // preconditions:
      Contract.Requires(s != null);

      // postconditions;
      Contract.Ensures(Contract.Result<string>().Length == s.Length);

      char[] reverted = new char[s.Length];
      int i = 0;
      foreach (char c in s)
      {
        reverted[s.Length - 1 - i ] = c;
        i++;
      }

      return new string(reverted);
    }
  }
}

The first thing to notice is that we have added a reference to the System.Diagnostics.Contracts namespace. This is where the new library is located. For this to work you have also to add a reference in your project to the Microsoft.Contracts assembly that has come with the Code Contracts installation.

The first method that we invoke on Contracts is a precondition that specifies that this method cannot accept an input string which is null (it would accept an empty string though). The second method is a postcondition asserting that this method guarantees that the string returned by this method will have the same size as the input string.

Obviously you are free to add more preconditions and/or postconditions if your domain logic requires so. But what exactly happens at run-time if either a precontion or a postcondition is not met? The answer is: it depends. After installing Code Contracts, project properties displays a new tab at the bottom named “Code Contracts” where you can tweak the contracts behavior for each of the build configurations that you have defined (Debug, Release, etc…).

Let’s concentrate on Runtime Checking for now: after you have checked it, you can decide which kind of contracts to enable; you should refer to official documentation for a complete explanation of all the options. For now, let’s just pick “Full” and check “Assert on contract failures”. With this choice, pre and postconditions will be tested at runtime and if any of them is not met a dialog will be shown detailing the failing condition.

So, let’s try calling the Invert method with a null string and let’s see what happens. Add the following code to the class above, compile and run.

public static void Main()
{
  Console.WriteLine(Invert(null));
}

This is what you should see:

As you can see, this looks exactly like using Debug.Assert calls from System.Diagnostics (many of us, myself included, used debug asserts in place of preconditions). In reality, contracts are much more powerful since

• you can not just enforce preconditions but also guarantee postconditions and other class invariants
• contracts knows about class hierarchies: you can define contracts on interfaces and base classes and they will be inherited from derived classes
• it’s possible to analyse compliance to contracts in a static way, even without running the code!

We’ll discuss about all this in the next post. Stay tuned!

Next post in the series: Code Contracts: Invariants.

According to the Wikipedia, a ghostwriter is a

professional writer who is paid to write books, articles, stories, reports, or other texts that are officially credited to another person.

As the name seems to imply, Ghost-Doc plug-in for Visual Studio is something like that: instead of typing in the XML documentation for your source code yourself, Ghost-Doc does the heavy-lifting and fills it for you.

Suppose you have a very simple class like the following:

public sealed class TestGhostDoc
{
    double CalculateVAT(double priceOfGoods, double VATPercentage)
    {
        return (priceOfGoods + priceOfGoods * VATPercentage);
    }
}

Now you want to add XML documentation for the CalculateVAT member function. All you have to do is to right-click somewhere on line 3 (I prefer to use the CTRL + SHIFT + D since I love shortcuts), select “Document This”, and Ghost-Doc will fill the XML documentation for you like the following:

public sealed class TestGhostDoc
{
    /// <summary>
    /// Calculates the VAT.
    /// </summary>
    /// <param name="priceOfGoods">The price of goods</param>
    /// <param name="VATPercentage">The VAT percentage</param>
    /// <returns></returns>
    double CalculateVAT(double priceOfGoods, double VATPercentage)
    {
        return priceOfGoods += priceOfGoods * VATPercentage;
    }
}

As you can see, Ghost-Doc, beside filling the structure for you, also fills the contents using a set of rules based on the order of the words (the only thing that is left is filling the content of the returns tag). Note that words are recognized successfully only if you use the recommended Camel and Pascal casing appropriately (which you ought to be doing anyway because you follow to the naming conventions).

Member functions is not the only place where you can use Ghost-Doc: class names, constructors, enums, properties, event, etc… they are all supported as expected.

namespace TestGhostDoc
{
    /// <summary>
    ///
    /// </summary>
    public sealed class User
    {
        /// <summary>
        /// Gets or sets the first name.
        /// </summary>
        /// <value>The first name.</value>
        public string FirstName { get; set;  }

        /// <summary>
        /// Gets the address.
        /// </summary>
        /// <value>The address.</value>
        public string Address { get; }
    }
}

Can you spot the difference between the documentations of the two properties that Ghost-Doc has generated?

Advanced use

Ghost-Doc has a complete customization window:

In these tabs you can

• modify/add templates that Ghost-Doc uses to document a language element
• define your own acronyms, that will always be rendered in all-caps by Ghost-Doc, even if you have written them in lower case inside a language element name to be compliant to the naming conventions
• modify/add the list of words which define qualities, that Ghost-Doc will reorder in a special way. For example, since size is on this special list “FileBufferSize will be worded as “the size of the file buffer” instead of “the file buffer size” .
• modify/add the list of words that shall never be preceded by “the” (the so called “no the” words).
• Modify the way true, false, and null keywords are represented
• Create a custom text that will be appended to all comments the first time they are created; this text can optionally be dynamic and include the name of the author, or the current date, etc.. (this would be a bit over the top IMHO since it would be repeated for each and every function, property, etc…).

With Ghost-Doc, you have no more excuses not to write complete and accurate XML source code 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.

UPDATE: I have created a PDF version of the shortcuts that you can download and print. You can find it here.

I have started my career as a programmer learning (and loving) the Emacs editor; later I used for quite some time the VI editor on a remote server. It’s no wonder that I have become accustomed to use keyboard shortcuts extensively while editing my programs. Luckily, Visual Studio 2008 IDE that I now use on a daily basis comes with its own set of keyboard shortcuts that can make my programming hours more pleasant and productive.

My Favorite Shortcuts

I have tried to collect here the shortcuts I use dozens of times everyday.

I don’t fancy regions too much (I tend to prefer classes with few and short methods, so whenever I feel like I’d need regions to me that is a code smell); that’s why you won’t find them listed here. I also usually don’t care about shortcuts to handle files (new / open, etc…)  and adding items to a project, since I am usually quicker using the mouse there. But without further ado, her comes the list.

Microsoft has a nice poster with the complete list of Visual Studio 2008 C# shortcuts. There are other shortcuts that I routinely use that are related to VS plug-ins (e.g. GhostDoc), but that is the topic for  another post.

Wish List

There are a few shortcuts that I’d love to have readily available in Visual Studio:

• join a line with the previous (J in VI)
• create an inline comment. that is, move the cursor to a specific column and insert a ‘//’ to start a new comment. (M-; in Emacs)
• format (wrap) multiline comments (M-q in Emacs)
• center screen at current line (CTRL+l in Emacs)
• an interactive replace mechanism (M-% in Emacs)