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?

  • 1
    Charge everyone $1 for each time they break the build... You'd be surprised how much it curbs careless mistakes. – Berin Loritsch Feb 25 '11 at 17:04
  • +1 because your comment inspired 3 excellent - and different - answers. – Carl Manaster Feb 25 '11 at 17:11

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).

  • Can't use Martin Fowler's (otherwise good) advice when you're refactoring code written by others. Also, I suppose the developer who deprecated the methods should remind his colleagues to use the new methods from time to time without being too annoying to speed up the transition. I'm under the impression that the deprecated methods in the Java class library will always exist for backward compatibility, but I may be wrong. – blizpasta Feb 28 '11 at 2:47
  • @blizpasta, depends on how many clients the API in question has. If you have half a dozen, all within the same department, it may take some discussion and arguments, and a few months to complete the transition under normal circumstances. If you have millions of users and billions of LOC of client code all around the world, then yes, you will most probably never remove those deprecated methods. – Péter Török Feb 28 '11 at 8:28

You can almost always avoid these problems by refactoring in two steps. In the first step, introduce the new code, and deprecate the old code. When all teams have migrated to the new code, delete the old code. I also use this technique to incrementally refactor a single module. In this way I can limit the amount of code that must be changed between test runs.

  • 2
    When I have done this, I was often able to change the old code to call the new code. This allows it to become a stub method, and provides the (hopefully) improved code for clients of the old method. – BillThor Feb 26 '11 at 1:03

Note that this is one of the primary reasons to have a build server, which runs tests.

If anything happens that will break a given program, you are told as quickly as possible and can hunt the culprit down and resolve the issues while the details are still fresh.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.