When writing a library/API for the first time I'll usually start by sketching some ideas on a white-board or loose-leaf while thinking about how different parts of the system interact. This usually results in an interface that I'll adhere to when I go to develop some concrete implementation.

I'll get half-way through writing the implementation when I realize that I need to make a change to the interface. For example, I realize that I've exposed too much implementation detail to the client and that the interface can be simplified.

Is this bad-practice, and should I actually know exactly what my interface will look like before I start coding any implementation?


In my situation I'm assuming that the interface doesn't already exist and we're creating it for the first time. So it's the first time that the interface will exist, and we are working on the very first implementation of that interface. So I want to know if in my situation, it's okay to make changes to an interface while coding the implementation.

  • 1
    Possible duplicate of "Public APIs are forever: Only one chance to get it right"?
    – gnat
    Feb 27, 2017 at 21:20
  • What you experience is entirely normal. Feb 27, 2017 at 21:21
  • While close, I do not think I agree with the duplicate. This question is asking about a developer writing an interface that is still in development, the dupe target is asking about a major public API that has been released and many developers are using it.
    – user22815
    Mar 2, 2017 at 0:27
  • @Snowman I thought about that while writing this question, and figured that somebody might think it was a duplicate (understandably so). I was considering not even asking this question. I tried to clarify what I meant as much as possible.
    – Snoop
    Mar 2, 2017 at 0:44

2 Answers 2


Yes, it is perfectly fine and normal. It is not really normal to know everything about how your system will work and what it will need to do when you're still in the whiteboard stage.

  • I sort of thought so. Usually once we get an interface defined and at least one implementation finished, we don't really see many changes to the interface after that. But when the interface is first defined, it seems to be a completely different story...
    – Snoop
    Feb 27, 2017 at 21:29
  • I would also say you shouldn't be creating interfaces at that stage anyway IMO. Create the interface after the implementation is fleshed out. Then replace discrete references with the interface.
    – Greg Bair
    Mar 22, 2017 at 1:59

Changes are inevitable thus they need to be managed.

Make sure to have a clear versioning scheme (search for semantic versioning, for instance), have a very explicit changelog and state clearly what you consider is part of the public API.

For instance, in some cases, adding an optional argument to a function can break backward compatibility if the number of arguments is not expected to change.

Also, there are tools to help you design an API. Test driven development is one of them.

  • While I agree with this, I think that even the interface is subject to change when you're trying to implement it for the first time. I think it's the feedback you get from writing the code that helps you clearly understand what you're really after...
    – Snoop
    Mar 2, 2017 at 0:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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