JavaScript Style: Functions within Functions

So like many others are probably doing I am wrestling with how to create a large JavaScript codebase that is maintainable. Part of how is based on technology stack decisions made by others. Specifically the use of Angular and TypeScript, but I do get to make a lot of calls about style and structure.

One thing that I have been thinking off and on about is declaring functions within functions. I have some instinct against doing this and I wanted to think about the nature of this instinct and whether it needs to be tossed while developing new JavaScript instincts.

The core of this instinct comes from the desire to keep functions short. I am all about short functions. (Note: that I often try to use the word function correctly unlike JavaScript itself, but for this entry I will bastardize the word following the JavaScript way.) If I can't read your entire function on a page or it's cyclomatic complexity creeps above 5, I get agitated. I have found that short functions tends to create more easily understood code. There are two key reasons for this. 1) A function for the computer represents a stack frame, but since computer languages are essentially a translation between human understanding and machine instructions the notion of a function has a human meaning. A function is a unit of understanding. I look at a function understand what it does then simplify that it my mind with something like "it sorts" or some thing like that that hides the complexity. 2) Part of this is the fact that functions force comments. I am not talking about JavaDocs (which I hate), but rather the name of the function. Breaking out code into a function forces you name that function and to specify what goes into it and what comes out. It also provides a scope and things can be isolated to that scope acting as a comment on those variables. This is a form of commenting that is going to be accurate.

So short functions are good, but suppose you have a piece of functionality in one function that is too big. You wisely break it into two pieces. With part A calling part B. You can divide them up so they exist separately. Using a tool like TypeScript you might label part B as private. The other option is to have B inside A. This makes A longer, but the function still has its role of encapsulating an idea, but it additionally gives you information about where the function is used. But the function still gets long and make me have to read more when I read a function. The function might have several functions as part of it and may stretch off the page which is bad. This is a little meaningless because you could just pretend the function signature was lower and you would be fine. I think the solution that makes sense is using an editor that allows you to collapse sections. When you looking at a function you can collapse all the interior functions and you can look at the function as a whole easily.

Instincts developed using non-functional programming do not necessarily carry over to more functional programming languages. Placing functions in the scope they are used is a powerful way to communicate information.