Javascript Functions as a Mind Map

In Clean Code: A Handbook of Agile Software Craftsmanship, the author describes the optimal structure of an agile function:

The following advice has appeared in one form or another for 30 years or more.

1. Functions should do one thing.
2. They should do it well.
3. They should only do that function.

In order to make sure our functions do one thing, we need to make sure that the statements within our function are all at the same level of abstraction.

Usually, the statements are themselves made of functions that also do one thing, leading to a recursive structure. If you think about it, the basic structure of functions is Mind Map. We will illustrate this at the end of the article.

Javascript is really one of the best languages to illustrate this Mind Map concepts because in javascript, functions are first class citizens and functions can be nested very naturally. So let's take a very common example in javascript: the testing of some new feature: the feature is only enabled in some predefined ratio of the page views and then we compare performance vs. the old feature. For example, imagine you want to compare the user experience of two designs of the same button. The cool name for this methodology is Ab testing.

As an example, let's dig into the code for the creation of a COOOOL Button: sometimes, we will use the new style and sometimes the old style:

function createCOOOOLButton(){
    if(shouldUseNewStyle()){
        createNewStyleButton();
    } else {  
        createOldStyleButton(); 
    }
}

In this post, we will focus on the implementation of the function shouldUseNewStyle(). This function is not the most complex function one has ever written, but it is neither so trivial. There are different constraints to deciding whether we want to use the new/old style:

1. Ab test value (generated by the server or randomly)
2. Url parameter (enforce new/old design - mostly used for dev/test phases)
3. Enforce new design for fancy users

Let's try to express this complexity in a single line of code where all the parts belong to the same level of abstraction.

function shouldUseNewStyle(){
    function isEnforcedByUrlParam() {...}
    function isEnabledByAbTest() {...}
    function isEnforcedByUserCategory(){...}
    return isEnforcedByUserCategory() || isEnforcedByUrlParam() || isEnabledByAbTest();
} 

Hey!!! Wait a minute. How do you implement all those functions? The answer is very simple: NEVERMIND. Or more accurately, at the level of abstraction of shouldUseNewStyle, it is of no interest to dig into these details. Writing all those details into separate functions is the essence of the structure of an agile function. It ensures that:

1. The code is structured into small blocks
2. All parts of the blocks belong to the same level of abstraction

Exactly like a Mind Map!!! (Be patient, and wait until you see the illustrating image at the end of this post...) As a consequence, the code is readable and there is no need to comment it: the code comments itself!

Now, we can continue our recursive journey into the details of the implementation. Let's say, we want to read the code of isEnforcedByUrlParam(). No problem, just unfold the line (any descent IDE supports folding/unfolding: even vi!!!) and here is the result

function isEnforcedByUrlParam() {
    function getUrlParameter(variable) {...}
    return getUrlParameter('cool_button_new_style') === '1';
}

It's that simple! The enforcement by url occurs if, and only if, the cool_button_new_style url parameter is switched on. Again very readable. Again, we don't care about the implementation of getUrlParameter() - at this level of abstraction.

Let's end our recursive journey here. Just before you go back home, let me keep my promise and summarize in a single picture the whole structure of the agile function we have described. Let me introduce the Mind Map!!!