soledad penadés

You might have heard that "*Utils" classes are a code smell.

Lots of people have written about that before, but I tend to find the reasoning a bit vague, and some of us work better with examples.

So here's one I found recently while working on this bug: you can't know what part of the Utils class is used when you require it, unless you do further investigation.

Case in point: if you place a method in VariousUtils.js and then import it later...

var { SomeFunction } = require('VariousUtils');

it'll be very difficult to actually pinpoint when VariousUtils.SomeFunction was used in the code base. Because you could also do this:

var VariousUtils = require('VariousUtils');
var SomeFunction = VariousUtils.SomeFunction;

or this:

var SomeFunction = require('VariousUtils').SomeFunction;

or even something like...

var SomeFunction;
lazyRequire('VariousUtils').then((res) {
  SomeFunction = res.SomeFunction;
});

Good luck trying to write a regular expression to search for all possible variations of non-evident ways to include SomeFunction in your codebase.

You want to be able to search for things easily because you might want to refactor later. Obvious requires make this (and other code manipulation tasks) easier.

My suggestion is: if you are importing just that one function, place it on its own file.

It makes things very evident:

var SomeFunction = require('SomeFunction');

And searching in files becomes very easy as well:

grep -lr "require('SomeFunction');" *

But I have many functions and it doesn't make sense to have one function per file! I don't want to load all of them individually when I need them!!!!111

Then find a common pattern and create a module which doesn't have Utils in its name. Put the individual functions on a directory, and make a module that imports and exposes them.

For example, with an equations module and this directory structure:

equations
  linear.js
  cubic.js
  bezier.js

You would still have to require('equations').linear or some other way of just requiring linear if that's what you want (so the search is "complicated" again). But at least the module is cohesive, and it's obvious what's on it: equations. It would not be obvious if it had been called "MathUtils" -- what kind of utilities is that? formulas? functions to normalise stuff? matrix kernels? constants? Who knows!

So: steer away from "assorted bag of tricks" modules because they'll make you (or your colleagues) waste time ("what was in that module again?"), and you'll eventually find yourself splitting them at some point, once they grow enough to not make any sense, with lots of mental context switching required to work on them: "ah, here's this function for formatting text... now a function to generate UUIDs... and this one for making this low level system call... and... brainsplosion" 😬

An example that takes this decomposition in files to the "extreme" is lodash. Then it can generate a number of different builds thanks to its extreme modularity.

Update: Another take: write code that is easy to delete. I love it!