Best practice: The resolve comment

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.

Getting developers and testers to trust each other

“The developers are ignoring our input!”

“Tester? Eh, guess he wasn’t good enough to get a job as a developer.”

Ever heard that before?

One of the keys to good QA is to have a team with a high level of trust. Actually, that’s one of the keys to good anything, when a team is involved. But right now we’re talking about testing.

Trust, of course, has to be earned. And it has to go both ways. So what do the testers need to do to earn trust from the developers, and what do the developers have to do to earn the testers’ trust?


Do a good job

Know the product. Know the business. Know the code base. Know the history. Know the context. Understand how all of these fit together.

There is no excuse for a tester not to know just as much about the product as the developers do. Testing is often viewed as the “easier” job in software development, one that doesn’t require as much skill as coding. That is simply not true. As a tester, you need to be deeply technical, highly logical and strongly creative, even if you never write a line of code. Expect nothing less from your own work than you would expect from the best developer on the team.

Even if you get everything else in this blog post right, nobody will trust you if you are incompetent.

Communicate clearly

One of the most important tasks of a tester is to provide information about bugs we have found. There is almost nothing a developer appreciates more than a well-written bug report. On the other hand, there is almost nothing that irritates a developer more than a badly written bug report.

If you aim to build trust between yourself and your developer, which type of bug report should you choose to write? Exactly.

(How to write a good bug report is a blog topic of its own – I will return to it)

Be reasonable and pragmatic

As testers, bugs are important to us. Especially the ones we just found, or the ones we worked really hard to find. It can be annoying when our bug reports are wontfixed or postponed to next release. It can be really annoying when the release goes out the door and you know about all the bugs that haven’t been fixed.

Deadline’s going to happen, though, and it won’t help you to be grumpy about it. Do what you can to inform the relevant stakeholders about the quality and the risk, and be reasonable about it. If you make a huge fuss about every minor issue, everyone will ignore you when you found the disaster that really needs to stop the release.


Do a good job

Don’t code in a way that causes stupid bugs. Regressions are stupid bugs caused by unmaintainable code with low modularity and no unit test coverage.

Testers don’t like stupid bugs. It makes them have to repeat the work they did last week just because they can’t be reasonably confident that the bugfix you did in one part of the code didn’t break anything somewhere else.

Even if you get everything else in this blog post right, nobody will trust you if you are incompetent.

Don’t assume it’s not a bug

The type of developer that annoys testers the most are those who always assume a reported problem is not a bug – and especially not a bug in their part of the code – until it has been proved to them beyond all doubt. Those who instinctively close all bug reports from junior personnel without even reading the details, and will only grudgingly accept reopening it after involvement from the junior tester’s managers.

Sure, some bug reports will turn out not to be actual bugs. If you get a lot of these from the test team or a specific tester, you should bring it up with them. In all likelihood, though, if there’s a bug report, there is an actual problem somewhere, even if you don’t see it at first glance. As a developer, you are responsible for the quality of the product, and it should be expected of you to make an effort to improve it. A dismissive attitude towards the testers is the surest way to get less help with that.

Communicate clearly

A tester almost always works with too little information. Tell them what you did, how you did it, what kind of side-effects it could have, what the risks are, how to configure it, and they will be forever grateful.

Your ten minutes of writing up this as you close your development ticket will save the tester hours, potentially days, of figuring it out on their own. The tech writers will be happy too.

Take an active part in quality improvement

Ask the testers how the product can be made more testable. Add test hooks where needed. Create test apps. Do some basic testing of your own products before sending them off to the testers. Refactor. Make downpayments on technical debt. Make use of the testers’ expertise to make your own work better.

The tester’s job description

Most of the blog posts both here and in my other blog fall into the category “too obvious to even write about”. In fact, most of my blog posts end up not getting written at all, because I think what I have to say is so obvious nobody will ever bother reading it. It’s my personal form of writer’s block, one that I am aiming to overcome. Everything I think about is of course obvious to me once I’ve thought about it. That doesn’t mean it’s obvious to everyone else – particularly to those outside of or new to the field of testing.

So, then, the tester’s job description. What is it?

Doh, that’s obvious! It’s testing the product!

Of course it is. And I have worked with many people – both within and outside the test teams – who have argued that this is the only thing the tester should concern themselves with. Everything else is better left to others in the organization.

I’ve never been content with this view. As a tester, I have always seen it as my job to do what I can to make the product better, and to put in my effort where it can make the biggest difference. I believe it is not just my right, but my obligation to stick my nose in other people’s business, if I see room for improvement that affects the product quality.

For example, if you as a tester know (as all testers should know) that code reviews are significantly more effective at finding bugs than system tests are, are you going to encourage the development teams who don’t do systematic code reviews to start doing them, or will you shut up and just run your tests?

Or, if you see signs of an architectural choice that you know is bad practice and believe is likely to cause problems further down the road, even if it may be years in the future, do you file a bug report, or are you satisfied that the feature passed all your functional tests, and send the build on its merry way?

How well I have been received varies greatly. Some developers and managers are defensive. I was once told in very clear language that this was none of my business, after politely asking whether or not the project implemented unit tests. But most are welcoming and eager to take part in the joint tester/developer effort to make the product the best it can be. Sometimes it takes time to build up the trust to get there – but that is a topic for another blog post.