Click here to Skip to main content
15,867,453 members
Articles / Desktop Programming / Windows Forms
Article

Comment Reflower Add-in for Visual Studio .NET

Rate me:
Please Sign up or sign in to vote.
4.92/5 (37 votes)
1 Jan 20054 min read 84.9K   733   58   24
A Visual Studio .NET 2003 add-in that reflows (rewraps) text in comments to make them easier to read.

Comment Reflower in action

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 80th 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.

Comment reflower configuration

Usage

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

Comment Reflower in action

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.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


Written By
Web Developer
United States United States
Ian has written a lot of C++ code in his life. Some of it even does useful things.

Comments and Discussions

 
BugVS 2003: menu items disappear after VS is reopened (w/solution) Pin
statc4-Aug-11 19:19
statc4-Aug-11 19:19 
QuestionVisual Studio 2008? Pin
fspafford16-May-08 6:45
fspafford16-May-08 6:45 
AnswerRe: Visual Studio 2008? Pin
Thomas Wells18-Sep-09 11:53
Thomas Wells18-Sep-09 11:53 
GeneralDoes this utility support VS2005 Pin
Martial Spirit14-Jul-07 12:55
Martial Spirit14-Jul-07 12:55 
GeneralRe: Does this utility support VS2005 Pin
Ian Nowland31-Jul-07 8:57
Ian Nowland31-Jul-07 8:57 
GeneralThank You Again! Pin
John R. Shaw28-Apr-07 10:40
John R. Shaw28-Apr-07 10:40 
GeneralThank You! Pin
John R. Shaw10-Apr-07 3:18
John R. Shaw10-Apr-07 3:18 
GeneralRe: Thank You! Pin
John R. Shaw10-Apr-07 5:23
John R. Shaw10-Apr-07 5:23 
QuestionVS XML comment bug Pin
workerbuzz18-Jan-07 13:48
workerbuzz18-Jan-07 13:48 
AnswerRe: VS XML comment bug Pin
Ian Nowland18-Jan-07 20:52
Ian Nowland18-Jan-07 20:52 
QuestionTab indents vs. wrap column broken? Pin
nobot06-Sep-06 14:53
nobot06-Sep-06 14:53 
AnswerRe: Tab indents vs. wrap column broken? Pin
nobot06-Sep-06 15:00
nobot06-Sep-06 15:00 
GeneralCompatibility troubles with VS's code indentation Pin
Mr. Baz28-Jul-06 0:58
Mr. Baz28-Jul-06 0:58 
Questionhow to use it in vs.net 2005? Pin
hiberhe10-Apr-06 5:16
hiberhe10-Apr-06 5:16 
AnswerRe: how to use it in vs.net 2005? Pin
Ian Nowland10-Apr-06 10:03
Ian Nowland10-Apr-06 10:03 
NewsFYI: NEW Home Page for the Comment Reflower Pin
kkm00021-Mar-06 0:43
kkm00021-Mar-06 0:43 
Generalit'd be nice to reflow code, too Pin
Jimmyyy17-Sep-05 9:11
Jimmyyy17-Sep-05 9:11 
GeneralGreat! Pin
Michael Kennedy1-Feb-05 18:33
Michael Kennedy1-Feb-05 18:33 
GeneralA small problem. Pin
ForogarTree13-Jan-05 8:21
ForogarTree13-Jan-05 8:21 
GeneralRe: A small problem. Pin
ForogarTree13-Jan-05 8:25
ForogarTree13-Jan-05 8:25 
GeneralRe: A small problem. Pin
Ian Nowland13-Jan-05 22:34
Ian Nowland13-Jan-05 22:34 
GeneralRe: A small problem. Pin
ForogarToo18-Jan-05 6:44
ForogarToo18-Jan-05 6:44 
GeneralFor Evc++ and VC++ 6.0 Pin
Kshitij Ashta5-Jan-05 13:07
Kshitij Ashta5-Jan-05 13:07 
GeneralExcellant! Pin
FocusedWolf4-Jan-05 11:10
FocusedWolf4-Jan-05 11:10 
This is truely useful...especially appreciate the capability to reflow any comments that are selected...like a whole class :P

One suggestion i have is option to add in a period at end of any comment that doesn't have one...including inside those function sumary blocks and the other ones for passed in and returned values...man is remembering to add a period or to check all those annoying.

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.