Want your bug reports to be clear? Don’t tell us about the bug in the repro steps.

If your bug reports include Repro Steps and Results sections, you’re half way to success. However, the other half requires getting the information in the right sections.

People have a hard time with this. Repro steps should be the actions leading up to the bug. But they should not actually describe the bug. The bug should get described in the Results section (i.e., Expected Results vs. Actual Results).

The beauty of these two distinct sections, Repro Steps and Results, is to help us quickly and clearly identify what the bug being reported is. If you include the bug within the repro steps, our brains have to start wondering if it is a condition necessary to lead up to the bug, if it is the bug, if it is some unrelated problem, or if the author is just confused.

In addition to missing out on clarity, you also create extra work for yourself and the reader by describing the bug twice.

+1 on comment for Result before Expected, for better reading flow.There are also situations when you don't know what is expected, or have a couple of alternative solutions; where it would be confusing to have it in the middle.

I agree with this approach.When i write bug reports, i first describe the encountered issue, after which i provide the steps to reproduce, then the Actual Results and then the Expected Results.This is the approach that all the developers from the company i work for prefer and find it easier to follow in order reproduce and understand the bug.

Who am I?

My typical day: get up, maybe hit the gym, drop my kids off at daycare, listen to a podcast or public radio, do not drink coffee (I kicked it), test software or help others test it, break for lunch and a Euro-board game, try to improve the way we test, walk the dog and kids, enjoy a meal with Melissa, an IPA, and a movie/TV show, look forward to a weekend of hanging out with my daughter Josie, son Haakon, and perhaps a woodworking or woodturning project.