Source Code Comments – Time for a revamp

[If you’re impatient then check out the image here to jump straight to the reason behind this post.]

When Microsoft first declared there intent to include support for comments within the C# language I was overjoyed. I was so taken with the idea that I wrote a VB6 add-in that would parse VB6 source comments prefixed by ‘/ and convert them into a HTML page which documents the class. Importantly it also provided a real-time preview window for the current method/property.

As it turned out when .NET was finally released I landed a job coding in VB.NET rather than C#. There were a couple of freeware tools around that would allow the XML documentation files to be produced from VB.NET source code. They were OK but it really wasn’t the same as having the compiler validate comment references. Also most of the tools we tried were a little flaky and prone to crashing every now and then.

Jumping ahead a few years and I’m using C# with Visual Studio 2005 on a large scale project. On this project I was responsible for writing a lot of architecture and doing my best to make sure it was documented. We used NDoc to produce MSDN style Help via MSBuild and our continuous integration engine (CruiseControl.NET). We also had to produce a script that would correctly register the generated v2 Help file to have it integrate seamlessly with the Visual Studio documentation. Setting this up was tricky. It required us to debug and fix the latest NDoc build to properly support generics, use another third party tool to generate the required Help registration goo, write custom NDoc tags for inserting images (like class diagrams) and creating FAQ indexes etc. It would also take about an hour to run (over our 40+ project solution).

But NDoc is dead!

Yes, but as everyone knows Sandcastle lives! The first few drops of Sandcastle were really quite scary. Config files here there and everywhere, write your own scripts to produce the end result. But whilst Microsoft were concentrating hard on getting the fundamental engine right the community came to the rescue  with Sandcastle Help File Builder (SHFB). A full featured, easy to use GUI to produce Help v1, v2 and HTML documentation using the Sandcastle engine. The recent builds of Sandcastle coupled with SHFB and we’re finally back (in fact slightly ahead) of where NDoc left off. The SHFB has even been built to look and feel just like the NDoc GUI – nice!

Sandcastle - UriToThumbnailConverter 

Some HTML v1 output from Sandcastle using SHFB.

Source Comments are ugly

However, having had a chance to write a fair amount of source comments on this particular VS2005 project, one thing became obvious. Improving the quality of the externally viewed documentation (e.g. in dexplore, or HTLP Help Viewer) had a directly negative effect on the readability of the same documentation within the source files (e.g. Visual Studio).

In other words – adding more markup to the source comments made them harder to read in Visual Studio. Yet I want the both of best worlds. I want to be able to produce useful documentation integrated with MSDN but at the same time I want those comments to be easily read by the developer when they are right there in the source.

/// <summary>
/// This <see cref="IValueConverter"/> allows image paths in XAML to be efficiently converted into
/// thumbnail images which could, for example, be used to populate an <see cref="ItemsControl"/>.
/// </summary>
/// <remarks>
/// <para>
/// This converter relies on the image file referenced by the string representation of the value
/// having a thumbnail image stored as part of its metadata. This will be likely for any image that
/// has been taken direct from a modern digital camera. Digital cameras  record a thumbnail image
/// for their own internal processing. This thumbnail "lives" with the metadata, e.g. EXIF tags that
/// record other information such as when the image was taken, the various camera settings etc.
/// </para>
/// <para>
/// If the string representation of the value does not represent a valid file, or the file is not accessible
/// for any reason then a default image will be returned.
/// </para>
/// <note>If this converter is used with a non-string value it will perform a <c>ToString()</c> on
/// the method in order to generate a string which will then be translated to a URI used to
/// load the image.</note>
/// </remarks>
/// <example>
/// The following example shows how the converter can be used in XAML.
/// <code lang="XML" title="Using the UriToThumbnailConverter in XAML" numberLines="true">
/// &lt;converters:UriToThumbnailConverter x:Key="uriToThumbnailConverter"/&gt;
/// ...
/// &lt;Image Source="{Binding Path=FilePath, Converter={StaticResource uriToThumbnailConverter}}" Height="90" /&gt;
/// </code>
/// </example>
public class UriToThumbnailConverter : IValueConverter
{
/// <summary>
/// Converts a string containing an image path (URI) into the thumbnail <see cref="BitmapSource">bitmap</see>
/// image contained within the image.
/// </summary>
/// <param name="value">The value produced by the binding source.</param>
/// <param name="targetType">The type of the binding target property.</param>
/// <param name="parameter">The converter parameter to use.</param>
/// <param name="culture">The culture to use in the converter.</param>
/// <returns>
/// A converted value. If the method returns <see langword="null"/>, the valid <see langword="null"/> value is used.
/// </returns>
public object Convert(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
{
try
{
BitmapFrame bitmap = BitmapFrame.Create(new Uri(value.ToString()), BitmapCreateOptions.DelayCreation, BitmapCacheOption.OnDemand);
return bitmap.Thumbnail;
}
catch
{
return System.Drawing.SystemIcons.Exclamation.ToBitmap();
}
}

So what’s the solution?

Well – back in those Visual Studio 2005 days I used to use a little tool called CR_Documentor which was written as a DXCore add-in. This provided a real-time preview window of what your source comments would look like once marked-up. This was really useful as there was nothing more annoying that doing a whole bunch of source comments only to find the next day (after the nightly documentation was produced) I had made some silly error with my markup causing corrupt, incomplete or missing documentation. Admittedly the build I was using used to struggle keeping up with some of the really large namespace documentation (e.g. 500+ lines), but it did a good job for the small stuff.

Configuration settings for CR_Documentor.

But please Microsoft, I want more!

What I really want is source comment markup integrated in the Visual Studio editor. When I’m browsing source code I don’t want to see angle brackets and tags all over the place. I want to see clearly readable documentation. When I want to edit the source comments then you can show me the angle brackets. Or better yet – given only a limited set of documentation and standard HTML tags are supported – why should I ever need to see the tags? Give me a limited document editor with a set of extendable “regions” and some basic bold/italic etc. formatting. (Click the image below to see in its full glory what could be a preview of Dev10).

Visual Studio Help Editor

An impression of what source code comment viewing could be like in Visual Studio.

So everyone knows that fixed-width fonts are out, and more readable proportional fonts are in. So why can’t we also get some WYSIWYG capabilities in the editor?

Some features of the new inline WYSIWYG source comment editor:

  1. Comments can be collapsed completely, or to a single line (as per existing region style collapse) using the expand collapse arrow to the left of the class/member. (Not sure how the arrow does a three state collapse – but hey why not?)
  2. Comment sections can each be collapsed to the heading as per MSDN comments.
  3. Default collapse settings for comments are configurable via Visual Studio settings.
  4. It should look nicer than my hacked “Frankenstein” screenshot which is more or less just overlaying the Sandcastle output over a Visual Studio editing window. In particular the comments should be de-emphasized.
  5. Hmm… what else?

Resources:

Sandcastle – Microsoft’s source code documentation engine

Sandcastle Help File Builder – NDoc-like GUI for Sandcastle

GhostDoc – does a “spooky” job of commenting your code for you.

CR_Documentor – real-time preview window of source comments marked up

XML Documentation Comments Guide – explains the various comment tags for VS 2003, 2005, NDoc and Sandcastle

2 thoughts on “Source Code Comments – Time for a revamp”

  1. The post is not clear. What are you trying to say?. Are you announcing a new product/add-in? Or You are bitching about the current state of comments?

  2. Edddy,

    I apologise for the haphazard manner in which this post has been put together. The term ‘Bitching’ might be a little harsh. I’m suggesting that the idea of having source code comments it two-fold. First it is to assist the developer by providing immediate feedback in terms of intellisense tooltips on classes, members, parameters etc. Secondly its to produce online reference documentation – preferably one that integrates nicely with MSDN.

    I personally find that adding markup to create hyperlinks, tables, bulleted lists and code examples makes those important comments much harder to read in the Visual Studio text editor. Its also akin to writing HTML in notepad without having any preview of the result until the page has been viewed in another tool. However, unlike HTML which can be rendered easily by opening the file in a browser, previewing the source comments can be a very involved process (involving a full compile, running sandcastle, registering the Help v2 etc.) which could easily take 10 minutes.

    I think this feature (making source code comments much more readable and thereby effective) should be a feature that Microsoft include in an upcoming release of Visual Studio.

    I’d love to hear what anyone else thinks. Do you find source code comments useful? Do you read them in the code window? Do you like the way they collapse, and when they are collapsed do you think the tooltip provided is adequate?

Comments are closed.