Internal api development and committing procedure

Question

I am now on the job of extending and refactoring a set of APIs and core data structures that most of the other components depend on. The team is small (5 people ).

A manager told me that before checking in my changes, I should search throughout the code base, find out all the functions that are dependent on the APIs I have changed, and if necessary, modify them to make sure the whole software works. I was a bit astonished by this request.

In terms of procedure, I think all I should do is to test my own stuff, document, and provide instructions for others to update accordingly. What makes this request even worse is that I know unit tests are not thoroughly conducted for some components. How can I possibly be sure that my change wouldn't creat bugs in the component of somebody else? And the development is active, it's almost certain my push of changes for somebody else would create local conflicts everywhere.

Before rejecting this request, can anybody provide some other perspective to this request? What is the common practice for internal API update? Thanks.

Answer 1

It sounds like the big concern of your manager is to make sure the software is always in a working state in the repository. This is not an unreasonable request, as they could pull and compile it for release at any point, and they would want to be confident they are not releasing a bad build.

Your manager proposed one option, but this option has the problems you cited. You have to search the entire code base for calls into the API (which may not be 100% reliable). You have to edit code under active development by other teams, which can lead both to merge conflicts and interpersonal conflicts. You will be trying to refactor code that you may not totally understand (and don't have the backing of tests for). This approach can lead to... challenges.

There are other options. For example, it might make sense to refactor the old API into an adapter for the new API. This way, the new code is being called internally, while externally no one should need to change their code immediately. Over time, you can convert over by working with the other developers, not around them, all while keeping the code fully functional.

A benefit to this is that you could add in logging to the old API calls to find out where those calls are being made from, and how often they are being called. This way, you can prioritize certain areas for conversion while not having to change over everything at once.

This strategy wouldn't be without its challenges. For example, you might have naming conflicts between the two APIs. Developing a versioning scheme for your API will help, and will alleviate this problem in the future. You will need to support both APIs for a time. Since the old API will simply wrap the new API, changes should mostly fall on the new API. You may have to hack around incompatibilities (deprecated data structures, etc). This is par for the course, but it would limit this problem to a single place within your direct control.

Answer 2

My trick is to make sure that the compiler is doing allot of the work for you.

I'll mark a method or class as [Obsolete] to find all the places it's used, or simply use the find all references function. the [Obsolete] method is better as this will inform consumers at compile-time that an alternative technique has been provided.

Diagram the APIs classes and structures so you can identify self-contained functionality, helper functions, common themes and dependencies. If possible document the classes that consumers make use of to see how much of the APIs classes/fields/events can be made private or internal without harming the consumers. The smaller the public interface you need to maintain the more flexible you can be in your rework.

It can also be helpful to literally create public interfaces and add them into the API as a first step, subsequently any changes that you need to make to this interface will be reflected in a compiler error and you can easily find the consumers using find all references or similar.

Look for extension points built into the API and make use of them, don't reinvent the wheel or refactor large portions of code.. try to work with the code that's already there as much as possible.

If your using Visual Studio try this addin from Microsoft which can help you find corner cases in a the codebase that might need to be addressed and implement System.Diagnostics.Contracts which can help you find code that falls into those corner cases.

Try to include as many of the critical consumers of the API in the build for the APIs, this way though compilation will take longer, you will be notified at compile time of any issues that have arisen from your changes to the library.