Should all development, including refactoring work, be accompanied by a tracking issue?

Question

The debate: Should all development, including refactoring work, be accompanied by a tracking issue? (in our case, Jira)

The common ground: Our primary goal is quality. A working product, every release, is more important than anything else. Our codebase is old and automated tests are lacking; we are working on this but it's a long-term project, we need interim processes.

Position 1: Refactoring work must be tracked in Jira. If it is not obviously related to the change you are making then you must raise another issue. If you don't then the work bypasses review and testing and there is a risk to our primary goal. The argument has been made that PCI compliance (a near-future goal of the business) requires this level of tracking; I'm not in a position to say that is true or false with any level of certainty.

Position 2: Code quality is vastly important. The better it gets (to a point; a point we are nowhere near), the more likely we are to keep releasing a working product. Anything which puts a barrier, no matter how small, in the way of refactoring is a risk to our primary goal. Often, the IDE does the work for you, so it isn't likely to go wrong anyway.

The following cases have been made:

Would it satisfy both positions if a developer writes "Refactor" and the relevant revision numbers on a card? Honestly, this feels like it's going to make everyone equally unhappy. It still puts a level of resistance on doing the refactoring, but doesn't offer sufficient tracking.

What about having all-encompassing Jira issues that cover the refactoring work for an iteration? Yes, this removes the developer resistance layer, but I fear it also removes the tracking benefits of having a Jira issue. How do QA get a clear idea what to test? This seems to be a political solution, keeping everyone calm by adding in a light-weight but ultimately pointless process.

It seems to me that, given that both sides of the debate ultimately want the same thing, there should be a solution that makes everyone genuinely happy. We can't have been the first people to ask this question, so what experiences have others had in similar situations?

Answer 1

Perhaps I'm missing something here, but how does creating a ticket for work you are doing that doesn't fall within the scope of your other tickets a 'resistance layer'?

Have you recently implemented using a ticket tracking system? If so, then sit down and make your rules for using it and let the team know that they are expected to follow these rules. If this includes creating refactoring tickets for this work, so be it. You can't make exceptions early on or it could derail the whole process that your team is trying to set up.

If you've been using a ticket tracking system for a while, then I really don't understand why this would be a 'resistance layer'. Your team should already be use to having Jira open and looking at their tickets and should be comfortable making tickets.

If you wanted to keep all refactoring efforts in one place, create a main ticket for this, and have your team make tasks under it for work they are doing. Then it takes like 5 seconds for a dev to make a new task for this and they can log their time to that task.

Project managers, team leads, and developers need to know how much time is going to the refactoing effort. You don't want it to become a black hole of time. Having the tickets keeps developers accountable for their work while providing managers and leads a place to keep track of how many hour going to the effort.

Answer 2

Ideally yes.

Any change you make to the code base should have a reason behind it. This can be a customer request - the most common/likely, or an internally raised item - such as in your refactoring example.

This means that as well as tracking when a change was made you can link the changeset back to something that explains why the change was made. Why can't this just be the changeset comments? There are several reasons why this might not be suitable.

• There's not always a 1:1 mapping between work items and changesets - you might need several sets of edits to complete an item.
• The changeset comments aren't usually visible to non-developers or you might need to attach other documentation to the work item.

Answer 3

Code refactoring, while highly desirable to improve quality, is also an inherent risk. This is especially true when dealing with "foundation" code where a single bug will make the whole system fall down and solving a single "issue" will have side effects (perhaps unforeseen) throughout the entire application.

Regardless of what type of code is involved, when a refactoring is not limited to the code for a specific issue (ticket), QA should be involved and made aware of the parts of your code base that were affected. They will have to do a full regression test on those parts to ensure that nothing slipped by. And they will have to do so even, perhaps especially, if you have a full set of unit tests in place that make you feel confident about doing the refactoring. Unit tests test a lot, but they also miss a lot.

So, if code quality is important, yes, there should be as few barriers as possible to improving the code. But I fail to see how creating a ticket for this is a barrier. It simply ensures that QA gets it chance to (im)prove the quality of the code and should be something desirable, not something viewed as an obstruction.

Answer 4

I think that if you can't describe the refactoring more specifically than "refactoring", you're doing it wrong. Refactoring should have a definite purpose and scope. Tracking the refactoring tasks separately in JIRA not only makes auditing, review and testing easier, but also forces the refactorers to focus their minds on concrete goals ("remove a circular dependency between modules X and Y", for example) and will simply lead to better refactoring.

On the other hand, if the refactoring is really simple, local and just a byproduct of carrying out a diffent task, I'd wouldn't bother tracking it under a separate ticket and only document it in the original taks ticket, if it can have an impact on other people's work.

Answer 5

Yes, ideally every change you make in the code should be associated to a JIRA item and thus trackable. As others have noted, you should be able to identify why a certain change was made, and what other changes it is related to.

It is fine to have longer term refactoring Epics in a legacy project, we have them too in ours. However, you should strive to focus these on some specific area of the code, with a specific purpose, otherwise it is really hard to keep it under control. E.g. "refactor modules Foo and Bar to eliminate cyclic dependencies", "refactor class hierarchy A to remove duplications and clean up inheritance hierarchy".

When working on legacy code, having limited resources, one has to prioritize possible ways to reduce technical debt, to achieve the best possible return on investment. So analysing possible refactorings, their importance, risks, costs and benefits should be done anyway before starting the job. Also, tracking the progress of a larger scale refactoring and knowing when it is finished is important. Compared to these required tasks, IMHO the actual effort of administering a JIRA item is minimal.

The argument has been made that PCI compliance (a near-future goal of the business) requires this level of tracking

If you mean this, I can sort of understand why management fears of uncontrolled changes in the codebase, however change tracking is only a tiny part of the solution. You need thorough system testing and probably code reviews to ensure that no credit card numbers are leaked from the system via log files etc. Refactoring is not supposed to change the behaviour of the existing code, and you are supposed to have unit tests to prove this anyway (don't try to lean on the belief that automated refactoring tools can't break the code - you MUST have unit tests to avoid nasty surprises).

Answer 6

In an ideal world, Chris's answer is right. Any time you make a change to the code or any artifact associated with a software project, there should be a log of this. It should be submitted, approved, assigned to the right party, effort estimated, work carried out, total time recorded, and a short description of the change documented.

However, this isn't always feasible. For example, my IDE is configured to reformat a code file based on the organization's code guidelines. If I open a file and see that it doesn't match up, it's trivial to fix - CTRL+SHIFT+F on the file formats everything. Maybe a CTRL+SHIFT+O to fix imports. I do this right before or right after fixing the defect that I was assigned.

In that case, you always want to log the fact that you did it and how long it took, but not making the change now might be worse than going through the process of formally assigning and implementing the change. In some cases, it is easier to beg for forgiveness than to ask permission. It's up to you, as an engineer, to justify where exactly that line needs to be drawn.

Answer 7

By and large, refactoring should take place as a normal part of your workflow. In order to fix bug A, you need to test that bit of the method, and so you must extract it as method B. While you're doing that, you notice field C is very badly named, and so you rename it.

To my way of thinking, these normal refactorings get "charged against" the original bug A. They are submitted with the fix, reviewed with the fix, ticketed with the fix. They are part of the fix.

But there are larger, less-focused refactorings that happen, too. A general observation that class D is too big. It would be easier to work on if you eliminated the duplication in E. And those refactorings are among the riskiest ones you'll take on (particularly in a code base without tests). By all means, create tickets for those; put them through at least your normal review process.