Doing a big software refactor¹ is not a simple thing. There are lots of points that you should think about, from planning and prioritizing to team motivation and execution. Understanding these points in a structured and clear way is part of the job. The good news is that we’ve been in that situation before and have learned the key points you should worry about.

Here are the main points you should consider when planning and executing a big refactoring process.

Define your business goals

A big software refactoring process should not be started without clear business goals, otherwise it can suffer from a lack of commitment by your stakeholders. Here are some examples of goals:

• We’re doing a refactor so that we can plug in multiple payment gateways.
• We’re doing a refactor so that we can improve velocity.
• We’re doing a refactor so that we can have a multi-tenant architecture in order to simplify our infrastructure operations.

Measure progress

By its very nature, a software refactoring process is a technical effort, which is why it’s common for people not to measure its progress in the same structured way that they measure progress on development of new features. Don’t fall into that trap.

As with every task in a project, a refactor should always be planned and measured.

Pay attention to your team’s motivation

Working on a legacy codebase can be demotivating for developers, especially if they don’t have a feeling of progress, or if they don’t know when it’s going to end. When going with a refactoring process, you should keep this in mind.

Show your team they’re moving forward. Plan for small deliverables, so that you can continually ship stuff and celebrate the good work done. Also, think about developer rotation, which can help by maintaining motivation and keeping fresh eyes on the task.

Define your approach: pull or push?

Are you going to improve your codebase only when touching some bad part of it, or are you going to proactively choose which parts you’re going to improve?

Prioritizing

If you have a clear business goal, it’s easier to proactively choose which parts need to be improved to make that goal a reality. With the parts listed, you can apply your usual prioritization techniques.

But if you’re going to do a constant and big software refactor because you know the whole codebase needs to be improved, it’s more difficult to prioritize. This is because there are not just one or two main parts that need improvement, but lots of them. It’s difficult to know where to start.

One way to prioritize in that situation is to instruct your team to evaluate which parts need to be refactored based on their complexity and churn. By that we mean, whenever they are evaluating if some part of the code should or should not be refactored, they should ask themselves:

• “Is the complexity of that class too high compared to the others?”
• “Do we constantly need to make changes on that file?”

If the answers are both yes, that part is a good candidate for refactoring. Plot a chart of “class complexity X churn” and prioritize the parts that are too complex and that you’re changing every time.

The parts that have big complexity but don’t need to change constantly are not good candidates to be refactored because they’re parts that are ugly but usually work, and nobody needs to change them to do their everyday job.

Know when you’re done

A software refactoring process can turn into an endless endeavor if you don’t plan, prioritize and measure progress. You should treat it as a project. It should have a beginning, a middle and an end.

Test suite coverage

Your refactoring process should improve stuff that is already working without breaking anything. Make sure you have good test coverage, otherwise the process can generate more bugs than quality improvements.

Test suite performance

If your test suite is too slow, it will slow down the refactoring process since a software refactor is greatly based on continuously running the tests. Make sure the test suite performance is not a bottleneck.

Sponsors commitment

A refactoring process can take a long time: weeks, months. During that time the velocity in which new features are delivered will be compromised. Make sure that every business stakeholder understands the goals and the nature of that kind of work, so that they don’t give up in the middle of it.

What about you? Do you have any more tips on what to worry about when doing a big software refactor? Share with us!

The post Key points to consider when doing a big software refactoring first appeared on Plataformatec Blog.

Not only physical matter deteriorates, software does too

It’s known that physical matter deteriorates. People accept that and have always dealt with it. What people don’t accept so easily is that software “deteriorates” too. Unlike physical matter, it doesn’t happen due to some physical or chemical phenomenon. It usually happens because of some business change or people change. Let me give you an example.

Imagine you’re leading the tech or product team of a startup; you’re the CTO. You already launched your product’s first version, and it was a success. Your business model was validated, and now you’re in a growth stage. That’s awesome! But it has its costs, and it brings a new set of challenges.

The first version of your product is working, but the codebase is not in the shape you’ll need from now on. Maybe your team’s velocity is not as good as it used be. Your team keeps complaining about the code quality. The CEO and the product director want new features, and your current projections will not meet the business needs.

It’s not uncommon that one of the main sources of all these problems is the poor quality of your product’s codebase. You may need a refactoring ¹ or a rewrite.

When the codebase is not in good shape, everyone can get frustrated

If the internal quality of your product is not good, everyone becomes frustrated.

Your whole team, including developers, will get frustrated because they would like to ship features faster, but the current code quality and architecture are not helping.

The IT, product, and software departments suffer because they’re not able to meet the expectations of the other departments.

The customer also suffers because of frequent bugs, how long it takes for them to be resolved, and how long it takes new features to be launched.

You get the picture.

Identifying the symptoms

It’s the leader’s job (let’s say the CTO) to identify when a refactor or a rewrite is needed. In order to do that, he or she can look around for some symptoms, like the ones below:

• Everything is hard: Almost every feature or bug fix your team needs to do is hard. It was not always like that. You remember the good old days when your team was fast and everything ran smoothly.
• Slow velocity: Your team’s velocity decreased or is decreasing. When you were building the first version of your product, it was fast to develop a new feature, and your team used to build lots of them every iteration. Now it’s different.
• Slow test suite: Your test suite takes 10x, 20x, 30x more time to run than before.
• Bugs that don’t go away: Your team fixes a bug, then in a week or so it appears again. Every now and then your team is fixing a regression bug.
• Your team is demotivated: Your team keeps complaining that working in the project is not as productive as it was in the past. A single person can’t build one feature alone; there are too many moving parts.
• Knowledge silos: There are some parts of the software that only a single developer knows well enough to maintain. It’s difficult for the rest of the team to work with that specific code.
• New developer ramp-up time is taking too long: When new developers join the team, it takes too much time for them to be fully productive.

The reason you got into one of these situations is probably not a technical one. Maybe you needed to deliver too much, too fast while you were building the first version of your product. Maybe your team didn’t have the maturity and experience in the past they have now. Analyzing the root cause is important too, but you need to do something else. You need to solve your problem.

If you’re experiencing the symptoms above, you probably have a low internal software quality problem. Recognizing the symptoms is already a big step. The next step is to think of solutions. Some solutions you may take include refactoring or a rewrite process.

Refactor or rewrite?

There’s no definitive guide about when you should do a big refactor or a rewrite, because it depends on a lot on your context. That said, there are some rules of thumb that you should consider when evaluating which solution to go with:

When to rewrite

• The technology you use is outdated, and it’s not maintained anymore.
• Your software is really slow, and changing the architecture is not enough or is not viable.
• The supply of software developers that know the technology you use is low and decreasing.
• There are new technologies that offer a significant advantage compared to what you’re using.

When to refactor

• The technology you use is still maintained and relevant.
• It’s viable to improve your application in an incremental fashion.
• The problem you’re solving is just technical and not a business one.

Choosing one of these options is not an easy decision, and once you go with one of them, there will be an entire new set of concerns you’ll encounter. Stay tuned, in our next blog posts we’ll talk about what to consider when doing a big refactor or a rewrite.

Now I would like to know about your experiences. Have you ever been in a similar situation? How did you identify that your problem was low internal software quality? Please share with us!

The post The Symptoms of Low Internal Software Quality first appeared on Plataformatec Blog.