One of the most valuable practices the QA team introduced in my current employer’s R&D department is the resolve comment. As is usual with anything new, some developers and development teams took to it instantly, while others needed a bit more time to see the light. These days, however, it is considered a standard part of the development workflow in this department.

The resolve comment is written when a developer resolves a ticket for a feature or bugfix. Sometimes it can be just short of a novel, though usually it’s just a few short paragraphs.

In case of a feature, it explains how the feature was implemented, and notes what the implications might be for other functionality, hints of what should be tested, and any potential risks the developer can think of.

In case of a bugfix, it also explains what was wrong, how it was fixed, and often also notes what measures should be taken to ensure this type of bug does not occur again.

These comments are valuable to several people:

• It lets the developer who will do the peer review understand the issue a lot faster than just by looking at the code and a one-liner commit message.
• It lets the testers, also, understand the issue both faster and more thoroughly, which means better testing in less time.
• It also saves both developers and testers from a lot of back and forth as the tester tries to gather more information on the issue in order to test it properly.
• It saves the developers a lot of time and frustration if problems are discovered with this feature or fix in the future, and they need to go back and look at what was done and why it was done in that way.
• The process of writing down what was wrong, serves to highlight areas of the code that would benefit from a general refactoring or debt down payment
• The tech writers love it, especially for features.
• A more subtle advantage is that the writing of these messages is a repetitive reminder that many people in many roles are touched when the code changes. It is a low-level team-building activity!

If you are trying to improve quality, the first thing you need is to make sure that everyone involved has the information they need to do their part. This little rule is a good way to start.