Commenting Your Regex

Emily Shaffer has written a great post proposing commenting regular expressions by each individual atom.

It’s probably not a good idea to encourage your coworkers to think critically about what life would be like if you got hit by a bus, but the good news is that you can simultaneously document your regular expression and teach your coworkers some regex basics, if you comment them carefully!

Her argument is that by breaking down the regex pattern and commenting on each part makes it easier for developers to understand and read the code. I like this approach. Despite having worked with regular expressions for many years I still find myself pausing when I get to one in code as my brain slowly attempts to decipher its meaning. Properly documenting the expression would hopefully lead to more readable code.

I feel like this is an approach I am going to try and adopt going forward. I can see it being useful for developers of all experience levels even if you’re very experienced with using regex. I know that many developers (myself included) have been guilty of copying a regular expression from sources like StackOverflow; one good way of ensuring that the expression being inherited is understood and meets the requirements is to take Emily’s approach and break it down and learn from it whilst documenting it.

One thing I would add to her approach would be to make sure that all regular expressions in the code are unit tested. This helps not only ensure that the regex works as intended (for both successful matches and non-matches) but also helps others understand how you expect it to function.

If you ever have to work with regex I recommend taking time to read Emily’s Read-Writable Regular Expressions blog post.