SSW Rules for Regular Expressions

Home > SSW Standards > Rules > SSW Rules for Regular Expressions

Do you format and comment your regular expressions?
Do you test your regular expression?
Do you use resource file to store your regular expressions?

Do you agree with them all? Are we missing some? Let us know what you think.

Do you format and comment your regular expressions?

Regular expressions are a very powerful tool for pattern matching, but a complicated regex can be very difficult for a human to read and to comprehend. That is why, like any good code, a good regular expression must be well formatted and documented.

Here are some guidelines when formatting and documenting your regex:
1. Keep each line under 80 characters, horizontal scrolling reduces readability.
2. Break long patterns into multiple lines, usually after a space or a line break.
3. Indent bracers to help think in the right scope.
4. Format complicated OR patterns into multiple blocks like a case statement.
5. Comment your regex on what it does, don't just translate it into English.
# Match <BODY
<BODY
# Match any non > char for zero to infinite number of times
[^>]*
# MATCH >
>

Bad example: Comment that translates the regex into English.

# Match the BODY tag
<BODY
# Match any character in the body tag
[^>]*
# Match the end BODY tag
>

Good example: Comment that explains the purpose of the pattern.

(?six-mn:(Label|TextBox)\s+(?<Name>\w+).*(?<Result>\k<Name>\.TextAlign\s*=\s* ((System\.)?Drawing\.)?ContentAlignment\.(?! TopLeft|MiddleLeft|TopCenter|MiddleCenter)\w*)(?!(?<=\k<Name>\.Image.*)|(?
=.*\k<Name>\.Image)))

Bad Example: Pray you never have to modify this regex.

(?six-mn:
    # Match for Label or TextBox control
    # Store name into <name> group
    (Label|TextBox)\s+(?<Name>\w+).*

    # Match any non-standard TextAlign
    # Store any match in Result group for error reporting in CA
    (?<Result>
        # Match for control's TextAlign Property
        \k<Name>\.TextAlign\s*=\s*

        # Match for possible namespace
        ((System\.)?Drawing\.)?ContentAlignment\.

        # Match any ContentAlignment that is not in the group
        (?!TopLeft|MiddleLeft|TopCenter|MiddleCenter)\w*
    )

    # Skip any Control that has image on it
    (?!
        (?<=
            \k<Name>\.Image
            .*
        )
    |
        (?=
            .*
            \k<Name>\.Image
        )
    )
)

Good Example: Now it make sense!
Do you test your regular expressions?

Everyone writes unit tests for their code, because it helps developer to make changes in future without breaking existing functionalities. The same goes for regular expressions. A good regular expression will have a set of test cases to make sure any future changes does not invalidate existing requirements.

At SSW, we do not fix a regular expression until we have added a good and a bad test case.

If your application is driven by regular expressions, you need a good test harness. Here is an example of a test harness we use in Code Auditor.

Figure: Test Harness for regular expressions in Code Auditor.
Do you use resource file to store your regular expressions?
```
public static Queue getFilesInProject(string projectFile)
{
	Queue tempQueue = new Queue();

	TextReader tr = File.OpenText(projectFile);

	// RT (10/10/2005): New regex to support VS 2005 project files (.csproj & .vbproj)
	//(?ixm-sn:
	//# VS 2003
	//(?:RelPath\s=\s\"(?<filename>.*?)\")
	//|
	//# VS 2005
	//(?:(?<=Compile|EmbeddedResource|Content|None)\sInclude=\"(?<FileName>.*?)\")
	//)
	Regex regex = new Regex
	    (@"(?ixm-sn:(?:RelPath\s=\s\""(?<FileName>.*?)\"")|(?:(?<=Compile|EmbeddedResource|Content|None)\sInclude=\""(?<FileName>.*?)\""))");
	MatchCollection matches = regex.Matches(tr.ReadToEnd());

}
```
Figure: Regular expression is embedded in code (Bad)
The problem with this code is that the regular expression is embedded within the method and not easily testable without creating mock files on-the-fly, etc. Another issue with embedding regular expressions in-code is escaping issues - often people will forget to escape the special characters or escape them incorrectly and thus cause the regular expression to behave differently between the design and execution environments.

The way we deal with this is to put the regular expression in a resource file. Using a resource file, it solves the aforementioned issues, and it also allows us to leave a comment for the regular expression.

Figure: The regular expression (with comment) is stored in a resource file (Good)
```
public static Queue getFilesInProject(string projectFile)
{
	Queue tempQueue = new Queue();

	TextReader tr = File.OpenText(projectFile);

	Regex regex = new Regex(RegularExpression.GetFilesInProject);
	MatchCollection matches = regex.Matches(tr.ReadToEnd());

}
```
Figure: We can easily get the regular expression from resource file (Good)

Acknowledgements

Adam Cogann
Cameron Shaw
Tim Fletcher
Edward Forgacs

SSW Rules for Regular Expressions

Do you format and comment your regular expressions?

Do you test your regular expressions?

Do you use resource file to store your regular expressions?

Acknowledgements