Brave New Interface

This concerns the development of code libraries for all sorts of software.

The library is a separate collection of software, which is “called” by a user’s software, to execute a variety of tasks. The way the user’s software calls the library is through its interface. This interface describes what the library does, but not how it does them.

It is very common to add functionalities to a library, and, accordingly, to its interface — this should cause no problem for the user’s software. The user might not even notice such changes.

For the interface to change, so that the user has to alter their own code to accommodate it, is at least a very bad sign.

“We have completely redesigned the interface. It’s a whole new concept.” “Everybody will just have to bring their code up to date.”

Oh oh.

This is a sure sign of an unprofessional attitude.

Either take disciplinary action, or blame yourself for the chaos that is soon to ensue.

Best practises and RIGHT attitude

A new interface should be capable of everything the old interface did, with the only exceptions being where the old interface did something bad or dangerous.

It should therefore be an easy, almost mechanical, task to re-write the old interface in terms of the new one.

Moreover, it should have been part of the development process of the new interface. Doing this also proves that the new interface is properly an improvement.

The best way to check that the new interface does everything the old one did, and does it correctly, is to test existing software built on the old interface, but with it really calling the new interface.

The upgrade to the new interface should be as painless as possible, clearly documented, with the advantages being clearly explained.

It is usual practice to mark undesirable portions of the old interface as deprecated, which means, maintainers of the user code should be aware that the portion will be removed from the interface. But even that step should be taken only if continued use of the portion has clear disadvantages.

What you don’t want to hear

“We don’t have time to re-write the old interface.”

Since a real improvement of the interface should just do more than the old one, only better and more conveniently than the old one, this should be mostly a matter of calling the new interface from the old one.

If it’s not that easy, you need to ask why.

It is usually a very bad sign. Maybe the new interface doesn’t do what the old one did at all. Or maybe, it does something subtly different, that leads to problems. Or maybe, the new library itself is buggy.

“Users must be forced to do it the new, improved way, because, it’s new and improved.”

This is just an expression of ego.

If the new interface is really better than the old one, users should be encouraged to use it because of the new features, or improved functionality, or easier use.

If users have to be forced to update their code to a new interface, it is a sign that the new interface is not really an improvement.

Consequences

If you let this unprofessional beginner have their way, there will be consequences, including: