Visual Studio .NET 评论重排插件

• 下载最新安装程序和源代码 (SourceForge).
• 下载 1.1 安装程序 - 313 Kb
• 下载 1.1 源代码 - 122 Kb

引言

在我们第一年的计算机科学课程中，讲师告诉我们注释与它们所描述的代码一样重要。我们点头称是，并承诺遵循他们的建议，后来在我们开始职业生涯时，会努力兑现承诺。

近年来，以Visual Studio为代表的编程IDE在改进代码布局的一致性和质量方面取得了长足的进步，并通过智能缩进和语法错误下划线等功能提高了编写代码的便捷性。然而，注释却奇怪地被排除在这些改进之外——没有拼写错误下划线，而且换行必须手动完成。这使得我们很难兑现承诺，因为这种手动格式化似乎是浪费时间。

Comment Reflower 是一个Visual Studio .NET 2003插件，是我试图解决第二个问题所做的尝试。在我工作的地方，我们有一项编码准则，要求所有注释都应在第80个字符处换行，有一天，我厌倦了手动计数到80——我觉得电脑应该能为我做到。于是我坐下来写了一个插件。

特点

Basic

在许多文本编辑器中，此类功能的起点是指定段落由空行或不同的缩进级别分隔。事实上，这也是我的插件的起点，所以

// 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.

变成

    // 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.

然而，Comment Reflower 比这做得更好，它提供了两个扩展功能：项目符号点和断流字符串。

项目符号点

项目符号点就是普通的正则表达式，如果匹配到一行的开头，就会阻止前一行重排到它里面，并且可以选择允许下一行缩进到项目符号点的宽度。正则表达式是完全可配置的。但是，默认的如下：

• 带标签和连字符的编号注释，如“1) tag - ”
• 编号注释，如“1) ”
• 行首的连字符“- ”
• Doxygen风格的标签后跟连字符，如“@tag - ”
• Doxygen风格的标签后跟空格，如“@tag ”
• Doxygen风格的标签后跟空格，如“\tag ”
• 单个字符后跟连字符，如“0 - ”

所以根据这些规则

/**
 * 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             
 */

变成

/**
 * 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             
 */

断流字符串

断流字符串的基本思想是，有些内容如果在一行上，那么你永远不想重排那一行。这通过断流字符串（实际上是正则表达式）来实现，如果匹配到一行，则意味着对于该行，要么

• 它永远不会被重排，无论多长。这也意味着前一行不会重排到它里面。
• 或者它永远不会重排到后续行。这意味着如果该行太长，则会在任何前一行之前创建新行来处理溢出的内容。

与项目符号点一样，断流字符串是完全可配置的。但是，默认的如下：

• HTML换行标签。
• XML标签独占一行。
• 行内非空格元素之间的连续空格。
• （下划线）独自占一行的连续“-”。
• $Source RCS标签。

所以看看它的实际效果，这个

// <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

变成

// <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

其他特性

Comment Reflower 的另一个功能是它会尊重XML <pre> 标签，并且不会重排其中的任何内容，因此以下注释保持不变

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

配置

Comment Reflower 可以通过对话框进行完全配置，方式如下

• 支持的语言和块类型。默认情况下，支持C、C++、C#、Visual Basic 和 Jamfile 的注释，但添加更多语言也很容易。
• 项目符号点字符串。
• 断流字符串。

这是通过如下所示的对话框完成的。请注意，有完整的在线帮助，所以我不会在这里详细介绍如何使用这些对话框。

用法

配置完成后，使用方法非常简单，只需右键单击注释并选择“重排当前光标所在的注释”，如下所示

或者，您可以选择多个注释，然后右键单击并选择“重排选定区域内的所有注释”。请注意，这会重排选定注释块的全部内容，而不仅仅是选定的部分。

历史

• 05/01/01 - 初始文章版本，引用1.1版本。