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.
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:
However, Comment Reflower does better than this with two extended features: bullet points and break flow strings.
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:
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:
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:
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.
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.
- 1/1/05 - Initial article version referring to release 1.1.
Ian has written a lot of C++ code in his life. Some of it even does useful things.