GhostDoc

Thanks to the “Toolbox” column in this month’s MSDN Magazine, I have recently discovered an amazing and free developer tool: Roland Weigelt’s GhostDoc. GhostDoc is an add-in for Visual Studio that will automatically add XML comments to your C# or VB code.

Who cares? You do! Doesn’t Visual Studio 2005 have XML comments built in already? Yes, but not like this!

The cool thing about GhostDoc is that not only does it add the XML comment structure like Visual Studio does, it also adds the information that you as developer would otherwise need to add. It has its own built-in rules to parse through your code to come up with basic descriptions of what each member does (yes, you can define your own rules, although I’ve yet to do so myself) and populates the XML comments appropriately.

I’ve been spending so much time on BI projects lately that until the last few weeks I haven’t done any “real” traditional .NET development since the beginning of the year. Lately, however, I’ve been developing some custom SSIS Control Flow and Data Flow components and a few utilities for batch updates to large numbers of SSIS packages (hopefully I’ll have something to share on both of these fronts soon), so I’ve been spending some quality time with C# again. And GhostDoc is proving to be a major time-saver, especially for an anal-retentive comment junkie like myself. Take a look at this example:

I started out with this C# method:


public void CreateVariable(string variableName, TypeCode dataType,
bool readOnly, string variableNamespace, object value,
bool evaluateAsExpression, string expression,
string description)
{
object variableValue;

switch (variableNamespace)
{
case "System":
throw new ApplicationException("You cannot create new System variables");
case "":
variableNamespace = "User";
break;
}

if (SsisHelper.IsCastValid(dataType, value))
{
variableValue = Convert.ChangeType(value, dataType);
}
else
{
throw new ApplicationException(string.Format(
"Data type mismatch: unable to convert supplied value '{0}' into requested data type '{1}'",
value, dataType));
}

if (VariableExists(variableName, variableNamespace))
{
ssisPackage.Variables.Remove(variableNamespace + "::" + variableName);
}

Variable v = ssisPackage.Variables.Add(variableName, readOnly, variableNamespace,
variableValue);

v.Description = description;

if (evaluateAsExpression)
{
v.EvaluateAsExpression = true;
v.Expression = expression;
}
}

And with a single keyboard shortcut (Ctrl-Shift-D by default) GhostDoc added this XML comment header to the method:


/// <summary>
/// Creates the variable.
/// </summary>
/// <param name="variableName">Name of the variable.</param>
/// <param name="dataType">Type of the data.</param>
/// <param name="readOnly">if set to <c>true</c> [read only].</param>
/// <param name="variableNamespace">The variable namespace.</param>
/// <param name="value">The value.</param>
/// <param name="evaluateAsExpression">if set to <c>true</c> [evaluate as expression].</param>
/// <param name="expression">The expression.</param>
/// <param name="description">The description.</param>

Although some tweaking and editing will still be required, having this as a zero-effort starting point is a huge step forward. If you’re doing any .NET development, you owe it to yourself to check out this great tool!

You can download GhostDoc for free here: http://www.roland-weigelt.de/ghostdoc/

Advertisements

About ssimagine

My name is Matthew Roche, and I am a Senior Program Manager with the SQL Server product group at Microsoft. I work on Master Data Services and Data Quality Services, and have previously worked on SQL Server Integration Services. Although I work for Microsoft and will be posting on technical topics, I want to stress that this is a personal blog, and any opinions posted here are mine and mine alone. I built my career around SQL Server and Microsoft technologies for well over a decade before I joined Microsoft as an employee, and I plan on using this blog to share my personal experience and opinions. They may well be shaped by my experience on the SQL Server team, but they’re still mine, and not that of Microsoft, disclaimer, disclaimer, etc., etc..
This entry was posted in BI, dev, tools. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s