This is part of my series about writing cards for software development. See the introduction here and my previous post on story cards here.

Agile Cards - Bugs

The average bug report is next to useless. Often, they do not communicate the problem, and are cluttered with useless information. Unsurprisingly, this leads to poor outcomes when the wrong thing is fixed, or fixed in the wrong way.

Some teams will attempt to combat this with a plethora of mandated fields detailing environment, user, software versions, etc, date & time, and so on. Ultimately, this is self defeating, introducing more noise in to a system.

A bug card at it’s heart is a simple report of two items. The software did X, it should do Y. Everything else is context.

For example, when a bug comes from a change in requirements, it probably does not need time, accounts, or environment data, it just needs a simple explanation of what it does, and what the desired change is. However, when a bug is sporadic, and only shows up in certain environments, the report requires a whole raft of data that cannot easily be captured by pre-selected static fields.

Since these fields often don’t apply to a given bug, they are frequently empty or set to garbage values. This leads to bug reporters and developers alike outright ignoring the fields. Worse yet, a reporter who is forced to fill in a gigantic list of fields is less likely to bother submitting the report at all. If they do, they are less likely to engage their brain and put in crucial detail, since it’s “covered” by the mandatory fields.

Instead, bug reports can be reduced into two soft-defined fields of Observed Behaviour & Expected Behaviour. This open document allows reporters to expand out the document to the level of detail required.

Cheat Sheet

# Observed Behaviour
Description of the observed behaviour which indicates that there is a bug.
When, where and what triggered it.

# Expected Behaviour
Behaviour that would be expected if code was functioning correctly.

# Investigation
If there has been an investigation before the ticket was created, leave any findings here.

These may be links to logs, error messages, code references or other details that may help
with fixing this bug.

Theories around potential causes, known issues, similar bugs, and other related data belong
in this section.

Observed Behaviour

What the software is currently doing. Avoid assumptions, and resist the urge to dig into implementation details, stick to what it does. Include details on Where, When, and What triggered or otherwise caused the bug to appear.

However, it’s important to be clear on exactly the item what is not working. Be as specific as possible around what is happening, and leave what should be happening for the next section.

Examples of good Observed Behaviour

  • “Login screen in testing environment shows error message ‘user list priv x001’ when attempting to login with username test@example.com and associated password.”
  • “Clients Acme corp, Xen Inc, and Locaine all have instances in production of where the same payment transaction is applied multiple times to the same invoice. See attached list for affected known affected invoices.”

Examples of bad Observed Behaviour

  • “Login doesn’t work”
    • Lacks detail. Does not indicate if the login screen fail to load, failed to let a legitimate user login, or threw a specific error message in specific circumstances.
  • “During the loading process, a large quantity of data is shown to the user which then disappears. Doesn’t seem to be helpful. This is probably related to the data loading refactor done by Alex last year. We shouldn’t show data to the user yet.”
    • This is typical of many bugs reports. It’s a complaint about the behaviour of the application, but it’s not easy to determine which part of, or even which application is being referred to. Mixed in here is some supposition about what the cause may be, but no reference is given for tracking down the details. Finally, there’s no concrete course of action. Instead, if it’s not clear what the fix is, mark the bug as not ready for development, and discuss possible solutions face to face.

Expected Behaviour

This field defines what should happen. As with the Observed Behaviour field, the bug reporter should assume that the the developer is not familiar with this part of the application, and write the expected behaviour section verbosely and explicitly. This does not mean that the field needs to be long, just explicit.

Do not refer to external documentation in this section, as the presence of the bug shows that documentation has already been proven to be insufficient.

If the expected behaviour requires multiple changes, separate these into a numbered list of items. This separation helps with clarity and avoids re-work due to missed requirements.

Examples of good Expected Behaviour

  • “Valid usernames and passwords allow a user to login with error messages.” / “Invalid username or password shows the error message ‘Incorrect username or password, please try again’.”
  • “Format the invoice due date in the user preferred style, falling back to YYYY-MM-DD format (eg, 2022-12-30).”
  • “If a transaction is applied to a payment, it should not possible to apply it again, unless a reversal of the same transaction has already been applied.”

Examples of bad Expected Behaviour

  • “Fix the map loading screen in HomeBase found at /users/###/map”.
    • Does not specify exactly how to ‘fix’ the loading screen. While specific around the location of the problem, the word “fix” here is open to interpretation. Something maybe obviously broken, but there are a myriad of ways it can be fixed. It’s important to be specific here about exactly what ‘fix’ means.
  • Fix the date field to match others in the invoice.
    • This is a better example of specificity of how to fix a bug, but refers to existing implementations of a date field, rather than directly specifying behaviour. It’s entirely possible that other implementations of the date field are also broken, but in different ways.

Investigation / Context

The investigation field is the place for all the other various items that usually clutter bug reports. This includes links, log messages, examples of the defect, environment details, other similar bugs, backtraces, and the other minutiae. These details are important, which is why they have their own section.

Separating this detail from Expected & Observed behaviour clarifies exactly what is context, and what is a desired change. This is especially true when there are multiple bugs to be worked on by multiple developers that have overlapping areas of concern, or the context to a given bug is incredibly large.

Final thoughts.

A simple bug should be simple to file. It should be simple for a developer to pick up and solve without needing to bother the person who wrote it.

A more complex bug with multiple root causes and multiple fixes required can be expanded with the required detail and context.

These soft defined fields allow for both.

Next time

Next time I’ll tackle epic cards, which show up everywhere, but nobody seems to know what to do with.