Home > SSW Standards > Rules > SSW Rules for 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:
- Keep each line under 80 characters, horizontal scrolling reduces readability.
- Break long patterns into multiple lines, usually after a space or a line break.
- Indent bracers to help think in the right scope.
- Format complicated OR patterns into multiple blocks like a case statement.
- 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