Kudos to SubMain

One of the classic hemorrhoid for developers is cleaning up of code and documentation. Most developers take an attitude of “I’m in the business because I like to code, not write documentation!” Personally, I find writing documentation often works as an excellent code-review mechanism, but that’s another issue.

 

Often I inherit horrible code bases that I really do not want to spend days, weeks and months getting into shape before doing meaningful work on it  -- or even getting meaningful documentation (I often suck such projects into Enterprise Architect as a starting point). These code bases may come from RentACoder, offshore developers, contractors or former employees.  I favor FxCop and StyleCop as my coding targets, although some devs think they are pigs to conform to…

 

Serge Baranovsky at Submain was kind enough to make one of the internal build of CodeIt.Right available to me. To this I added another of their products, GhostDoc.  After running CodeIt.Right and automatically fixing hundreds of issues in one project, I compiled it and found a total of just one error as a side effect  in some 400 files --- The error was commenting out an overload for an extension :

 

BEFORE:

private static DataTable ToDataTable(this MembershipUser user) {…}

private static DataTable ToDataTable(this MembershipUser user, string tablename) {…}

AFTER

// private static DataTable ToDataTable(this MembershipUser user) {…}

private static DataTable ToDataTable(this MembershipUser user, string tablename) {…}

 

The code that broke using it was a ToDataTable(myUser) – instead of myUser.ToDataTable(). In other words, a pretty obtuse set of relationships to correctly analysis. Major KUDOS for only having such a minor side effect!

Did it get the code into “A” FXCop or StyleCop quality?

Nope – it cleaned up a lot of items, but as Submain posts indicates, they have hundreds of pending items. The items that I most lamented not being implemented were some common StyleCop issues:

• SA1516: Adjacent elements must be separated by a blank line.
• SA1503: The body of the if statement must be wrapped in opening and closing curly brackets.  
• SA1514: A documentation header must be preceded by a blank line or must be the first item in its scope.  (Ghostdoc does not generate comments with a blank line before) 
• SA1513: Statements or elements wrapped in curly brackets must be followed by a blank line. 
• SA1200: All using directives must be placed inside of the namespace.
• SA1508: A closing curly bracket must not be preceded by a blank line.  

When it added a copyright, the default setting did not include the pattern required for StyleCop:

// <copyright file="ContactUs.cs" company="Lassesen.com">
//     Company 2009 Lassesen.com
// </copyright>

 

instead:

 

// Copyright        : (c) 2009,2010 Lassesen.com. All rights reserved.

 

resulting in:

SA1634: The file header must contain a copyright tag.  

 

It would seem that these should be easy items to fix by just walking the lines in a file. I do not know if they prioritize according to the typical number of occurrences in common code (i.e. Code from SourceForge), but I would recommend they consider that approach.

Xml Documentation

The next issue was getting Xml documentation on the properties and methods…  GhostDoc worked wonders if I was prepared to spend a few days walking every method mindlessly.  The logical solution was to use a Macro to walk all files in the solution. At this point, I became a heretic to my Microsoft background and instead of re-inventing the wheel, I found the perfect macro given by J.B.Brown which required one very minor modification to work with the current GhostDoc (supplied by the folks at Submain – Thank you Marcel Roma!!).  I am actually disappointed that SubMain has not sucked this code into GhostDoc in the 8 months since Marcel posted the modification – i.e. the ability to run it on a document, project or solution basis.

 

The macro ran nicely – open,  modified and saved files without leaving artifacts.

 

One of the things that I was not happy with was GhostDoc did not handle Designer.Cs files.

For example:

 

ORIGINAL:

/// <summary>
/// SitemapPanel control.
/// </summary>
/// <remarks>
/// Auto-generated field.
/// To modify move field declaration from designer file to code-behind file.
/// </remarks>
protected global::Lassesen.Web.UI.WebControls.SiteMapMenuPanel SitemapPanel;

 

I removed the comments, and did GhostDoc on it and it came up with:

/// <summary>
///
/// </summary>
protected global::Lassesen.Web.UI.WebControls.SiteMapMenuPanel SitemapPanel;

 

It would be sweet if it put something into the description!  When I suck in CS files to Enterprise Architect, it would be sweet if something like this was produced:

 

I removed the comments, and did GhostDoc on it and it came up with:

/// <summary>
///  Site Map Panel control
/// </summary>
protected global::Lassesen.Web.UI.WebControls.SiteMapMenuPanel SitemapPanel;

 

OR EVEN BETTER, copy the Xml Documentation of the control as the second line – providing rich meta data.

 

Bottom line:

I use Resharper, JustCode and CodeRush regularly so the question is always, why use another one? In my book and environment, CodeIt.Right is worth it’s cost many times over. If you want to deliver obtuse source code; want to bill hundreds of hours cleaning up code inherited from elsewhere (Off shore, contractors etc); contend that documenting your code is just too too expensive --- then do not buy CodeIt.Right! Bill the hours and make yourself rich billing for mindless hours of work!

 

Resharper, JustCode and CodeRush are sweet while you write code – on a statement by statement basis. CodeIt.Right does things on a file, project or solution basis – a very different problem space.

 

For myself, I’m old school and believe in delivering high value per dollar. I also like to deliver clean documented code --- even when the customer is not willing to pay for it. I would recommend that every shop has at least one copy of it – owned by whoever is Mr.Code Review and Cleanup.

 

Again Kudos for two excellent products!