Imagine you’re working in a well tested project and you’re assigned a new bug:
GIVEN there's a button to send a notification WHEN I click that button THEN I receive a "button clicked" notification that has an "id" and "username"
Actual: The "button clicked" notification only has an "id".
You work on this bug and run all your tests. Unfortunately you notice that another test you didn’t even realize exists failed. This test is written with a title like, “The button clicked notification should NOT have a username”.
Now you start to wonder which is right: The bug you worked on or the test that contradicts it. You check the commit history message. It says something like “Ensure button notifications don’t include username”. The person who wrote the original test either doesn’t work at the company or simply doesn’t remember why they originally wrote the test.
This is not a common problem, but it happens enough to slow me down occasionally and make me question if I’m doing the right thing. It’s not enough to document “what” was worked on. The reason “why” the work was done needs to be documented, too. A good place to document “why” is in the commit message itself.
Ideally, the developer shouldn’t have to come up with the “why” themselves. It should come from the Product Manager and be known to the developer before they even start changing the code.
Where I work, we make this easy to follow by using a template for stories. It looks like this:
AS A _____ I WANT TO ______ SO THAT _______ //most important part
GIVEN _____ WHEN _____ THEN _____ //2nd most important part`
I’ll go into the details of this template in another article, but the “SO THAT ____” is the most important part because it explains the “why”. If you can tie each change back to the “… SO THAT …”, you’ll have a much easier time when you need to figure out which of the two contradicting changes is correct.