Regular Expressions. We all love them for the power and hate them for the obfuscation level.
This dialog is remotely based on a true story. All names have been anonymized, to protect the innocent.
Colleague from another team: “What is wrong with this Java regex for parsing a special floating point number expression? A team member wrote it and left for good. It does not work. I need to create it fresh.”
—Me: “Hard to say without knowing what you exactly need. Do you have tests?”
Colleague: “Are you kidding? Of course not.”
Colleague (bursts into laughing): “Clown g’frühstückt? Of course not.”
Colleague: “Yeah, that at least. Historical samples from real executions.”
—Me: “Could be worse. Let’s create a test setup.”
Colleague: “Test setup? That sounds hard! I do not have time for this.”
—Me: “But you have time to fix the unavoidable mistakes in PROD? Think again. It really is NOT that hard. In such a simple case, you will be more productive with TDD even in the short term. Any constraints for creating the test setup?”
Colleague: “Java 8, JUnit 4, Maven.”
—Me: “Not exactly my weapons of choice, but well… will do. Let’s get ready to rumble!”
Step 1: Create your setup with an empty test and regex
We use maven as a slim wrapper for pulling the right version of junit, building and running the tests.
Run and confirm: It’s green.
Step 2a: Create failing first test
We simplify here, by using just 1 single JUnit test file as
host of the Regex implementation and
place for the example definitions.
If you are in a true Java project developing more than a single regex, you will want to wrap it and separate it from the tests, of course.
Run tests. Red!
Step 2b: Fix it in the simple-most fashion
Run tests. Green!
Steps 3–∞: Iterate
Here I give a transcript of the remaining session. We skip some steps in between to shorten it.
End Result: Proven documentation
Now we have a piece of documentation with true discriminative power. <This> is intended behaviour. <That> is not. All future developers touching the code will thank you – including yourself.