Comment Reflower Add-in for Visual Studio .NET

• Download latest installer and source (SourceForge).
• Download 1.1 installer - 313 Kb
• Download 1.1 source - 122 Kb

Introduction

In our first year Computer Science courses, the lecturers tell us that comments are just as important as the code they describe. We nod our heads and promise to follow their advice, and later when we begin our careers, try to keep the promise.

In recent years, programming IDEs as exemplified by Visual Studio have made tremendous strides in improving the consistency and quality of code layout as well as increasing the ease of its writing, through its smart indenting and underlining syntax errors and the like. However, comments have been curiously left out of these improvements - there is no underlining of spelling errors, and word wrapping must be done manually. These make it hard for us to keep our promise, as this manual formatting seems like a waste of time.

Comment Reflower is a Visual Studio .NET 2003 plug-in that is my attempt to address the second issue. Where I work, we have a coding guideline that all comments should wrap at the 80^th character, and at some point, I just got tired of manually counting to 80 - it seemed the computer should be able to do it for me. So I sat down and wrote myself a plug-in.

Features

Basic

The starting point for this type of feature in a lot of text editors is to designate that paragraphs are separated by empty lines or by different indentation levels. And indeed, that is the starting point for my add-in, so:

// Paragraph 1 with inconsistent text wrapping. Paragraph 1 

// with inconsistent text wrapping.

// Paragraph 1 with inconsistent text wrapping.

//

// Paragraph 2 with inconsistent text 

// wrapping separated from paragraph 1 by a blank line.

//   Paragraph 3 with inconsistent text wrapping 

//   not separated from paragraph 2  

//   but with a different indentation level.

becomes:

    // Paragraph 1 with inconsistent text wrapping. Paragraph 1 with

    // inconsistent text wrapping. Paragraph 1 with inconsistent text wrapping.

    //

    // Paragraph 2 with inconsistent text wrapping separated from paragraph 1 by

    // a blank line.

    //   Paragraph 3 with inconsistent text wrapping not separated from

    //   paragraph 2 but with a different indentation level.

However, Comment Reflower does better than this with two extended features: bullet points and break flow strings.

Bullet Points

Bullet points are just regular expressions that, if matched at the start of a line, prevent the previous line being reflowed into it, as well as optionally allowing the next line to be indented the width of the bullet. The regular expressions are fully configurable. However, the default ones are:

• Numbered comment followed by a tag and a hyphen, like '1) tag - '
• Numbered comment, like '1) '
• Hyphen at the start of a line '- '
• DOxygen style tag followed by hyphen, like '@tag - '
• DOxygen style tag followed by space, like '@tag '
• DOxygen style tag followed by space, like '\tag '
• Single character followed by hyphen, like '0 - '

So with these rules:

/**
 * Comment reflower has two more sophisticated 
 * features:-
 * - Bullet Points
 * - Break Reflow Strings
 * 
 * Bullet Points have two main implementation points:-
 * 1) Firstly when recognised on the next line 
                   they prevent the currently processed line 
 *    from being flowed into them
 * 2) Secondly they can set the indentation level to be the right 
 *    side of the bullet point, so that when text is 
 *    reflowed it is done slightly indented, in the way Word processors do.
 *
 * Bullet points are just regular expressions matched against the start
 * of the line, and thus don't just have to be normal 
 * bullet points. For instance you could do:
 * @doxygentag the comment for a doxygen tag, 
         which will be wrapped at the right edge of the tag
 * @doxygentag2 the comment for a doxygen tag, which will be 
 *              wrapped at the right edge of the tag             
 */

becomes:

/**
 * Comment reflower has two more sophisticated features:-
 * - Bullet Points
 * - Break Reflow Strings
 * 
 * Bullet Points have two main implementation points:-
 * 1) Firstly when recognised on the next line they prevent the currently
 *    processed line from being flowed into them
 * 2) Secondly they can set the indentation level to be the right side of the
 *    bullet point, so that when text is reflowed it is done slightly indented,
 *    in the way Word processors do.
 *
 * Bullet points are just regular expressions matched against the start of the
 * line, and thus don't just have to be normal bullet points. For instance you
 * could do:
 * @doxygentag the comment for a doxygen tag, which will be wrapped at the right
 *             edge of the tag
 * @doxygentag2 the comment for a doxygen tag, which will be wrapped at the
 *              right edge of the tag             
 */

Break Flow Strings

The basic idea of break flow strings is that there are certain things that if they are on a line then you never want to reflow that line. This is implemented as break flow string being just regular expressions which, if matched on a line means, for that line, either:

• it will never be reflowed, no matter how long it is. This also means that preceding lines will not be reflowed into it.
• or it will never be reflowed into subsequent lines. This means that if the line is too long, a new line will be created to take the overflow before any proceeding lines.

Like Bullet Points, Break Flow Strings are fully configurable. However, the default ones are:

• HTML Line break tag.
• XML tag on a line by itself.
• Consecutive spaces anywhere on the line between non-space elements.
• (Underline) consecutive -'s on a line by themselves.
• $Source RCS tag.

So looking at this in action, this:

// <summary>

//    C# is fond of doing comments like this, which 

//    I don't particularly like because it wastes white

//    space, but because of the XML tag rule above it reflows okay.

// </summary>

//    

//   Title

//   -----

//   Underlines work as well, and also <BR>

//   tags which stop the previous line flowing into this,

//   and reflow into the next is prevented by the fact it has a double space.

//   Changed on:  1/1/2005

becomes:

// <summary>

//    C# is fond of doing comments like this, which I don't particularly

//    like because it wastes white space, but because of the XML tag rule

//    above it reflows okay.

// </summary>

//    

//   Title

//   -----

//   Underlines work as well, and also <BR>

//   tags which stop the previous line flowing into this, and reflow into

//   the next is prevented by the fact it has a double space.

//   Changed on:  1/1/2005

Other Features

The other feature that Comment Reflower has is that it respects XML <pre> tags and does not reflow anything within them, so the following comment is left untouched:

/*
 * <pre>
 * -----------------
 * |       |       |
 * -----------------
 * </pre>
 */

Configuration

Comment Reflower is fully configurable from a dialog in the following ways:

• Supported languages and block types. By default, C, C++, C#, Visual Basic and Jamfile comments are supported, but it is trivial to add more.
• Bullet Point Strings.
• Break Flow Strings.

This is done through dialogs like that shown below. Note that there is full online help, so I won't go into using these dialogs here.

Usage

Once configuration is done, usage is as simple as right clicking in a comment and clicking "Reflow Comment Containing Cursor", as shown below:

Alternatively, you can select a number of comments and then right click and select "Reflow All Comments In Selected". Note that this reflows the whole of selected comment blocks, not just the selected portions.

History

• 1/1/05 - Initial article version referring to release 1.1.