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.

The new year has just started and it’s time for me to share my professional life resolutions for the upcoming year.

Through books, articles, blogs, podcasts, one hears about that language, or that technology, or that process which would be great to try and learn. Unfortunately, since the spare time is not infinite, one has to make choices and concentrate on what might give the best return on investment in the short/medium term. The following are the two or three things which I have chosen to dive in this year:

Read the Blue Book

Domain-Driven Design by Eric Evans is one of the best book that I have come across on software design in a while. Not always an easy read (some say it’is “dense”), I am going through it slower than usual: every chapter is full of sound advices and deep concepts that take a while to sink in.

Luckily in my current project I will have the opportunity to apply many concepts from this approach. For this reason alone, this makes to the top of my list for 2010.

Learn Ruby

2009 has been for me the year of C#. The Pragmatic Programmer suggests to both to learn a new language every year and getting familiar with one scripting language. Most experts seem to agree that learning a language with a different paradigm from the one you use everyday is a big plus. Martin Fowler (who favors Ruby) states that:

[...] programming languages do affect the way you think about programming, and learning new languages can do a lot to help you think about solving problems in different ways. (It’s important to learn languages that are quite different in order to get the benefit of this. Java and C# are too similar to count.)

I am not expecting to become proficient with Ruby in the near future (after all, I will still be using C# in my every-day at work). However from what I have seen so far it really looks like a great language to learn, so I am looking forward to it.

Play with Subversion

In my previous job at Motorola I was developing in a mixed Unix and Windows environment; Rational Clearcase Multisite was the company-wide version control tool. Clearcase is a real heavy weight, and probably one of the few tools that can handle teams of hundreds of developers located anywhere word-wide.

When I landed my current job I had to switch to the much more limited (and widely hated) Microsoft Source Safe (hey… always better than no version control at all, right?) Luckily, rumors has it that we might soon migrate to Subversion.  Subversion is widely used in the open source community and I guess I’ll need it once I start playing with Ruby and downloading libraries etc…

Other Books to Read

Beside the blue book, there are a few other books that I plan to complete reading this year. I have already started Clean Code and Pragmatic Thinking and Learning. Next on my list is Working Effectively With Legacy Code and Agile Estimating and Planning. I promised myself not to buy any more book before I clean my current queue!

Stuff Left for 2011

As I mentioned, there are so many other things I would love to investigate and play with, but there is only so much time available, considering that 2010 will bring in .Net4.0 and C#4.0 that will surely be a priority.

Therefore, the following I guess will have to wait till 2011:

• Learning a functional programming language (possibly Haskell or F#)
• Getting familiar Domain Specific Languages (Martin Fowler is preparing a book on the topic)
• Play with Android and/or iPhone development
• The Next Big Thing from 2010!

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).

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:

[sourcecode language="csharp"]
public sealed class TestGhostDoc
{
double CalculateVAT(double priceOfGoods, double VATPercentage)
{
return (priceOfGoods + priceOfGoods * VATPercentage);
}
}
[/sourcecode]

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)