From e0b80576884f460b9c769fbb7cf581d99ef78a70 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Sun, 23 Jun 2019 17:48:08 -0300 Subject: [PATCH] New Chapter: Interface changes --- content/books/things-i-learnt/_index.md | 1 + .../boolean-parameters/index.md | 2 +- .../interface-changes/index.md | 35 +++++++++++++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 content/books/things-i-learnt/interface-changes/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index c534eca..382c95f 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -26,3 +26,4 @@ template = "section-contentless.html" * [Be Ready To Throw Your Code Away](throw-away) * [Future Thinking Is Future Trashing](future-trashing) * [Don't Use Booleans As Parameters](boolean-parameters) + * [Beware of Interface Changes](interface-changes) diff --git a/content/books/things-i-learnt/boolean-parameters/index.md b/content/books/things-i-learnt/boolean-parameters/index.md index 622ce01..7819692 100644 --- a/content/books/things-i-learnt/boolean-parameters/index.md +++ b/content/books/things-i-learnt/boolean-parameters/index.md @@ -29,4 +29,4 @@ interface to the outside of your class/module will still be clear. But _don't_ add flags/Boolean parameters to your functions. -{{ chapters(prev_chapter_link="/books/things-i-learnt/future-trashing", prev_chapter_title="Future Thinking is Future Trashing") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/future-trashing", prev_chapter_title="Future Thinking is Future Trashing", next_chapter_link="/books/things-i-learnt/interfaces-changes", next_chapter_title="Beware of Interface Changes") }} diff --git a/content/books/things-i-learnt/interface-changes/index.md b/content/books/things-i-learnt/interface-changes/index.md new file mode 100644 index 0000000..15d762d --- /dev/null +++ b/content/books/things-i-learnt/interface-changes/index.md @@ -0,0 +1,35 @@ ++++ +title = "Things I Learnt The Hard Way - Beware of Interface Changes" +date = 2019-06-23 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "interfaces", "apis"] ++++ + +Interfaces and APIs is what you give away to others. If you keep changing them, +you'll make everyone's life a sad life. + + + +When talking about [boolean +parameters](/books/things-i-learnt/boolean-parameters), I mentioned about +renaming the function. If you control the whole source where the function is +used, that's not issue, it's just a matter of search and replace. + +But if that function was actually exposed in a library, you shouldn't change +function names in a whim. That will break a lot of other applications beyond +your control and make a lot of other people unhappy. + +Remember, when you write [tests for APIs](/books/things-i-learnt/tests-apis), +you can see these kind of changes happening and you can see the kind of +changes you're doing on how they reflect externally. + +You can create the new functions and mark the current one as deprecated, +either by documentation or by some code feature. Then, after a few released, +you can finally kill the original function. + +(A dickish move you can do is to create the new functions, mark the current +function as deprecated and _add a sleep at the start of the function_, in a +way that people using the old function are forced to update.) + +{{ chapters(prev_chapter_link="/books/things-i-learnt/boolean-parameters", prev_chapter_title="Don't Use Booleans As Parameters") }}