From 06802dc15008757a90c687368f768305f65d1409 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Thu, 13 Jun 2019 14:56:31 -0300 Subject: [PATCH] Somebody stop me! --- .../thoughts/things-i-learnt-the-hard-way.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/content/thoughts/things-i-learnt-the-hard-way.md b/content/thoughts/things-i-learnt-the-hard-way.md index 685679e..f96a144 100644 --- a/content/thoughts/things-i-learnt-the-hard-way.md +++ b/content/thoughts/things-i-learnt-the-hard-way.md @@ -130,6 +130,47 @@ function documentation and find that you added an "and", it means the function is doing more than one thing. Break that function into two and remove the "and". +### Don't use Booleans as parameters + +When you're designing a function, you may be tempted to add a flag. Don't do +this. + +Here, let me show you an example: Suppose you have a messaging system and you +have a function that returns all the messages to an user, called +`getUserMessages`. But there is a case where you need to return a summary of +each message (say, the first paragraph) or the full message. So you add a +flag/Boolean parameter called `retrieveFullMessage`. + +Again, don't do that. + +'Cause anyone reading your code will see `getUserMessage(userId, true)` and +wonder what the heck that `true` means. + +You can either rename the function to `getUserMessageSummaries` and have +another `getUserMessagesFull` or something around those lines, but each +function just call the original `getUserMessage` with true or false -- but the +interface to the outside of your class/module will still be clear. + +But _don't_ add flags/Boolean parameters to your functions. + +### Beware of interface changes + +In the point above, 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 is actually exposed by 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. + +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.) + ### Good languages come with integration documentation If the language comes with its own way of documenting @@ -936,3 +977,5 @@ find/figure out. * Added a point about libraries. * Clarified a bit about why generalists win in the end. * Added a point about comments in blogs. + * Added a point about flags in functions. + * Added a point about API evolution.