29 ms·

You should never break interface. You should expand interface. If you do that.. then.. You never edit docs. You only add to docs.

mikekchar 8y ago
Works great for a year or two ;-) Never refactoring your interfaces means that you can never improve the design as you gain new information. It means you can never change to something more appropriate if the underlying use cases change. It means that you can't easily consolidate common functionality in a different place as new similar interfaces are constructed. In other words, you are locking yourself in to a brittle system that will degrade into a mess of spaghetti that nobody can understand. There are, of course, also downsides to refactoring. No simplistic rule of thumb will tell you your best approach.
- screaminghawk 8y ago
  You can have the best of both worlds by versioning your endpoints
  - nradov 8y ago
    Supporting and maintaining old endpoint versions is expensive. Especially if the old endpoint shares a back end data store with the new endpoint. You can get locked into a bad data model and unable to move forward. If you can do it then great, but it's just not always technically feasible or cost effective.
    - beart 8y ago
      If you are only ever adding and never refactoring, aren't you already locked in? I guess supporting one piece of technical debt is probably going to be cheaper than having to support a few legacy versions on top of the current version. However, the legacy version can at least be end-of-lifed eventually, whereas you would have to support all legacy features for the life of the product with the 'only add' method.
    - mikekchar 8y ago
      Yeah, you can sometimes build an adaptor to expose the old API on top of your new API, but other times you have to actually maintain 2 parallel implementations. It's always a hard choice. Or at least it should be if you are thinking it through all the way :-) A lot of times I find that developers lack experience of how legacy applications get the way they do. Either they have only ever worked on green field applications before (a surprisingly large contingent!) or they assume that the crappy legacy code was created because the previous developers were stupid. The reality is that most legacy systems were made with very reasonable decisions at the time, but that the world shifted under them. The mistake was locking themselves into their original decision and making it very expensive to change. The decision to never deprecate old APIs is one of those decisions that makes change expensive. Such decisions should always be made looking at the trade offs in cost. How expensive would it be if we changed this API? How expensive would it be if we don't change this API? Usually the second is far more expensive in the long run, but you have to take it on a case by case basis.
- polityagent 8y ago
  Or use a new name for the new interface whilst not breaking your old one. If your api is private then break it all you want, but if it's public and you want a large grateful user base then you should only grow. See rich hickeys talk "speculation" for a much better explanation of this.
- oldmanhorton 8y ago
  I believe in all(?) public windows COM interfaces, methods can only be added, not changed or removed. So it’s at least possible, modulo any concerns about the design or cruft of the windows api surface
gowld 8y ago
You can delete your interface once all clients are migrated off the interface. At that point, delete the docs. Yes, you should never change your interface. But docs can poorly written (bad implementation) and deserve edits, just as code can be poorly written and deserve edits.

mikekchar 8y ago

Works great for a year or two ;-) Never refactoring your interfaces means that you can never improve the design as you gain new information. It means you can never change to something more appropriate if the underlying use cases change. It means that you can't easily consolidate common functionality in a different place as new similar interfaces are constructed. In other words, you are locking yourself in to a brittle system that will degrade into a mess of spaghetti that nobody can understand. There are, of course, also downsides to refactoring. No simplistic rule of thumb will tell you your best approach.

screaminghawk 8y ago
You can have the best of both worlds by versioning your endpoints
- nradov 8y ago
  Supporting and maintaining old endpoint versions is expensive. Especially if the old endpoint shares a back end data store with the new endpoint. You can get locked into a bad data model and unable to move forward. If you can do it then great, but it's just not always technically feasible or cost effective.
  - beart 8y ago
    If you are only ever adding and never refactoring, aren't you already locked in? I guess supporting one piece of technical debt is probably going to be cheaper than having to support a few legacy versions on top of the current version. However, the legacy version can at least be end-of-lifed eventually, whereas you would have to support all legacy features for the life of the product with the 'only add' method.
  - mikekchar 8y ago
    Yeah, you can sometimes build an adaptor to expose the old API on top of your new API, but other times you have to actually maintain 2 parallel implementations. It's always a hard choice. Or at least it should be if you are thinking it through all the way :-) A lot of times I find that developers lack experience of how legacy applications get the way they do. Either they have only ever worked on green field applications before (a surprisingly large contingent!) or they assume that the crappy legacy code was created because the previous developers were stupid. The reality is that most legacy systems were made with very reasonable decisions at the time, but that the world shifted under them. The mistake was locking themselves into their original decision and making it very expensive to change. The decision to never deprecate old APIs is one of those decisions that makes change expensive. Such decisions should always be made looking at the trade offs in cost. How expensive would it be if we changed this API? How expensive would it be if we don't change this API? Usually the second is far more expensive in the long run, but you have to take it on a case by case basis.
polityagent 8y ago
Or use a new name for the new interface whilst not breaking your old one. If your api is private then break it all you want, but if it's public and you want a large grateful user base then you should only grow. See rich hickeys talk "speculation" for a much better explanation of this.
oldmanhorton 8y ago
I believe in all(?) public windows COM interfaces, methods can only be added, not changed or removed. So it’s at least possible, modulo any concerns about the design or cruft of the windows api surface

gowld 8y ago

You can delete your interface once all clients are migrated off the interface. At that point, delete the docs. Yes, you should never change your interface. But docs can poorly written (bad implementation) and deserve edits, just as code can be poorly written and deserve edits.