Refactoring – Best Practices for Renaming, Refactoring, and Breaking Changes with Teams

refactoring

What are some Best Practices for refactoring and renaming in team environments? I bring this up with a few scenarios in mind:

  1. If a library that is commonly referenced is refactored to introduce a breaking change to any library or project that references it. E.g. arbitrarily changing the name of a method.

  2. If projects are renamed and solutions must be rebuilt with updated references to them.

  3. If project structure is changed to be "more organized" by introducing folders and moving existing projects or solutions to new locations.

Some additional thoughts/questions:

  1. Should changes like this matter or is resulting pain an indication of structure gone awry?

  2. Who should take responsibility for fixing errors related to a breaking change? If a developer makes a breaking change should they be responsible for going into affected projects and updating them or should they alert other developers and prompt them to change things?

  3. Is this something that can be done on a scheduled basis or is it something that should be done as frequently as possible? If a refactoring is put off for too long it is increasingly difficult to reconcile but at the same time in a day spending 1 hour increments fixing a build because of changes happening elsewhere.

  4. Is this a matter of a formal communication process or can it be organic?

Best Answer

Each of the scenarios you listed falls under the category of "published API / code". This is difficult to refactor, so one should not change anything lightly. Rather, (s)he should negotiate the planned changes beforehand with all parties involved. It is at least as much a political issue as technical.

So the number one advice regarding this from Martin Fowler is don't publish your interfaces (project names and structures) prematurely.

However, if it is already done and it needs to be fixed, probably it is better to try to do the necessary changes in as few steps as possible, to minimize the disruption of other parties. Which is deviating quite far from the original concept of refactoring, but for a good reason.

Also, if possible, consider adding the new method (while deprecating the existing one) instead of renaming the existing one. This ensures that client code does not break, and provides a transition period for them to update their code to comply with the latest API. The drawback is that it complicates your API. Although the state is only temporary, however it may take considerable time before you can safely remove deprecated API methods (in the case of the Java class library, years).

Related Topic