Recipe 8.13 Documenting Your Regular Expressions

Problem

You have one or more complex regular expressions that may exist in a file outside of your code. You need a way to place comments within the regular expression itself. These comments will aid others in being able to read and maintain your regular expressions later on.

Solution

Add comments to the regular expression using the # comment character:

string matchPattern = @"\\\\                 # Find this:  \\
                        (?<TheServer>\w*)    # Server name
                        \\                   # Find this:  \
                        (?<TheService>\w*)\\ # Service name";

or add C#-style comments outside of the regular expression string:

string matchPattern = @"\\\\" +                // Find this:  \\
                      @"(?<TheServer>\w*)" +   // Server name
                      @"\\" +                  // Find this:  \
                      @"(?<TheService>\w*)\\"; // Service name

When using these expressions in a Regex object, the RegexOptions.IgnorePatternWhitespace enumeration value must be added to the options parameter of the Regex object constructor:

Regex RE = new Regex(matchPattern, 
  RegexOptions.Multiline | RegexOptions.IgnorePatternWhitespace);
MatchCollection theMatches = RE.Matches("The source text goes here...");

Discussion

With large and complex regular expressions, it is desirable to break up the expression into manageable pieces and to identify what each piece does. For example, the regular expression in the Solution section will pull the server and service pieces out of a UNC string. By breaking up the regular expression onto separate lines and adding comments to each line, we have allowed other developers (who might not be familiar with regular expressions) to more quickly and easily read and maintain our regular expression.

Typically, you would use the string concatenation and C#-style commenting to comment a regular expression string. However, if you are retrieving the regular expression from an external source, such as a text file, regular expression style commenting (#) is the type to use.

With simpler regular expressions, you can get away with adding a C# comment outside of the regular expression string to indicate what it does. But adding comments to the regular expression itself greatly aids in understanding it.