Click here to Skip to main content
Click here to Skip to main content

Comment Reflower Add-in for Visual Studio .NET

, 1 Jan 2005
Rate this:
Please Sign up or sign in to vote.
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

Share

About the Author

Ian Nowland
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) Pinmemberstatc4-Aug-11 19:19 
QuestionVisual Studio 2008? Pinmemberfspafford16-May-08 6:45 
AnswerRe: Visual Studio 2008? PinmemberThomas Wells18-Sep-09 11:53 
GeneralDoes this utility support VS2005 PinmemberMartial Spirit14-Jul-07 12:55 
GeneralRe: Does this utility support VS2005 PinmemberIan Nowland31-Jul-07 8:57 
GeneralThank You Again! PinmemberJohn R. Shaw28-Apr-07 10:40 
GeneralThank You! PinmemberJohn R. Shaw10-Apr-07 3:18 
GeneralRe: Thank You! PinmemberJohn R. Shaw10-Apr-07 5:23 
QuestionVS XML comment bug Pinmemberworkerbuzz18-Jan-07 13:48 
AnswerRe: VS XML comment bug PinmemberIan Nowland18-Jan-07 20:52 
QuestionTab indents vs. wrap column broken? Pinmembereric.anderson6-Sep-06 14:53 
AnswerRe: Tab indents vs. wrap column broken? Pinmembereric.anderson6-Sep-06 15:00 
GeneralCompatibility troubles with VS's code indentation PinmemberMr. Baz28-Jul-06 0:58 
Questionhow to use it in vs.net 2005? Pinmemberhiberhe10-Apr-06 5:16 
AnswerRe: how to use it in vs.net 2005? PinmemberIan Nowland10-Apr-06 10:03 
NewsFYI: NEW Home Page for the Comment Reflower Pinmemberkkm00021-Mar-06 0:43 
Generalit'd be nice to reflow code, too PinmemberJimmyyy17-Sep-05 9:11 
GeneralGreat! PinmemberMichael Kennedy1-Feb-05 18:33 
GeneralA small problem. PinmemberForogarTree13-Jan-05 8:21 
GeneralRe: A small problem. PinmemberForogarTree13-Jan-05 8:25 
GeneralRe: A small problem. PinmemberIan Nowland13-Jan-05 22:34 
GeneralRe: A small problem. PinmemberForogarToo18-Jan-05 6:44 
GeneralFor Evc++ and VC++ 6.0 PinmemberKshitij Ashta5-Jan-05 13:07 
GeneralExcellant! PinsussFocusedWolf4-Jan-05 11:10 

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

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

| Advertise | Privacy | Mobile
Web01 | 2.8.140821.2 | Last Updated 1 Jan 2005
Article Copyright 2005 by Ian Nowland
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid