5

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?

Update

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.

Snoop
  • 2,718
  • 5
  • 24
  • 52
  • 1
    Possible duplicate of ["Public APIs are forever: Only one chance to get it right"?](http://softwareengineering.stackexchange.com/questions/188131/public-apis-are-forever-only-one-chance-to-get-it-right) – gnat Feb 27 '17 at 21:20
  • What you experience is entirely normal. – Bart van Ingen Schenau Feb 27 '17 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. –  Mar 02 '17 at 00: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 02 '17 at 00:44

2 Answers2

4

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.

FrustratedWithFormsDesigner
  • 46,105
  • 7
  • 126
  • 176
  • 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 '17 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 '17 at 01:59
0

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.

abstrus
  • 146
  • 3
  • 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 02 '17 at 00:46