DEV Community: Jordan Los

Interpreted Languages: Reading Source Code

Jordan Los — Thu, 07 Jul 2022 15:12:04 +0000

Types of Reading

In my previous article, Serious Jest: Making Sense of Hoisting, I noted the Jest docs say they hoist their mocks. Hoisting means the Javascript engine assigns references in memory to some objects before executing code. But for Jest, hoisting is executing mock statements before import statements. So even if you define mocks after your imports, they will execute first. That Jest uses hoist to mean something different is not at all obvious and why I wrote the article.

After posting, I was asked how I made the connection. The short answer is I spent a bunch of time stepping through Jest source code in my debugger. The longer answer is I followed a process I picked up in the humanities. Reading Plutarch's Parallel Lives may not seem like reading source code, but you have the same goal. You read to understand the intentions and ideas of another person.

How To Read a Book by Mortimer J. Adler and Charles Van Doren best describes the reading process. They describe four types of reading: elementary, inspectional, analytical, and syntoptical. Each type of reading played a crucial role in researching and writing the last article. I’ve structured this article around them.

Elementary Reading

Elementary Reading is being able to understand the grammar and syntax of a language. This level of reading is the prerequisite to understanding another person's ideas. There's not much to discuss at this level of reading for our purposes.

Inspectional Reading

Inspectional reading is strategic skimming. You want to grasp, as quickly as possible, the structure and meaning of a work. The sooner you learn the structure of a work, the sooner you can grasp its finer points. This means skimming the chapters, watching the movie first, or listening to a podcast.

The same principles apply to code. Skim docs, look at function names, and read short articles. By the end, you should have familiarity with key concepts, files, and docs. I read blogs on hoisting, browsed the Jest source code on Github, and watched a few youtube videos. I identified two critical areas while inspectional reading: the ECMAScript spec and a few key files in the Jest repo. I also had notes on scopes, closures, and the Javascript Execution Context.

Analytical reading

Analytical reading means reading for intent, structure, and relations. Different genres have different rules for these things as does code. Some parts of a file are "the main point" while others serve a supporting purpose. Since analytical reading is the most time-consuming and fruitful, prefer primary sources. Formal specs and source files are harder to read than summaries. But source docs give you unfiltered detail at a granular level. How do you know that blog post didn’t miss something relevant to your problem? If you haven’t read specs and source files, you’re trusting someone else’s interpretation.

I started with the ECMAScript spec section 9. It didn't have any direct answers, but I had a better mental model of what was happening when my tests ran. The ECMAScript spec made sense of the Closure section of the Scope tab in Chrome DevTools. Monitoring the closures section during debugging helped answer several of my questions.

Setting up the Debugger

Run node --inspect node_modules/.bin/jest --runInBand path/to/your/test¹
Open up Chrome and go to chrome://inspectand click Open dedicated DevTools for Node.
Open up your test file in Sources tab and run your tests

Using the Sources Tab, I executed the test line-by-line. I did this for test files, the components under test, and some Jest source code. The key Jest file I looked at was node-modules/jest-runtime/build/index.js. At each step, I monitored the Closure section and paid attention to the mocks. I monitored when the mocks received references and documented those changes. I then followed this line-by-line process for each of the four examples. Following code execution, while writing down my thoughts yielded the most results. I wrote out what I thought was happening, noted my questions, and made sure to answer every one of them.

This stage of analytical reading is when I figured out:

Jest alters a test file's execution order. Mocks execute before imports. This is Jest hoisting. Javascript hoisting happens before execution.
Jest collects it and describe blocks but then executes them later
When Jest was actually evaluating function expressions defined within the test files

When doing analytical reading across several works, you produce a lot of notes. Organizing those notes into something coherent is the next step.

Syntoptical Reading

Syntoptical reading is a term coined by Adler to mean reading across many authors. If analytical reading is conversing with a single author answering their own question, then syntoptical reading is conversing with many authors to answer your own questions. You then take your answers and synthesize them into a cohesive line of thought.

I wanted to know how Jest and Javascript handled different ways of creating mocks. Bringing notes from many sources together is a fuzzy process. I’d look at a note, get a question, and run through the debugger again. Or I'd peek at the ECMAScript spec. Or I'd go look at a couple of blogs to work out things like the Temporal Dead Zone.

Reading your notes across many works is when you make novel connections. I realized here that Jest executing a mock meant something different than I assumed. If the mock is executing, then the Javascript engine is operating in the execution phase. And if Jest hoists during execution, then it's not the same type of hoisting as in Javascript. This only became clear, however, after all the previous exploration.

A good sign the end is near is when you can create a rough outline from your notes. Here was one of my earlier outlines:

Sneaky Temporal Deadzone
Test Step Through
1. Import parent module
2. Jest function: requireModuleOrMock
3. Jest function: requireMock
4. Critical line of Jest code: node-modules/jest-runtime/build/index.js Line 802: const module = this._mockFactories.get(moduleID)()
ECMA Script Sepc
Function Declaration vs Function Definition
Jest Docs

This outline differs from the one I finally published. I still had questions and every time I answered one I saw a better way to organize my thoughts. The final iteration came after I had answered my questions on how the 4 examples were executed. When I put that final set of notes together, I could see there were 6 stages that each example went through. Those stages explained the differences in how the examples were executed. From that point, the rest of the article was filling in details from my exploration.

Conclusion

Code describes machine instructions which distinguishes it from other textual works. Despite its mechanical nature, source code still embeds ideas in human-readable language. So reading to grasp ideas in code will use the four types of reading I've mentioned. By understanding each type of reading, you can focus your intent when doing your research. So dig into that source code and make sense of your problem. All the rest is commentary.

About Jobber

Our awesome Jobber technology teams span across Payments, Infrastructure, AI/ML, Business Workflows & Communications. We work on cutting edge & modern tech stacks using React, React Native, Ruby on Rails, & GraphQL.
If you want to be a part of a collaborative work culture, help small home service businesses scale and create a positive impact on our communities, then visit our careers site to learn more!

Debugger explanation: ↩
- inspect allows you to access the test in your chrome dev tools
- runInBand prevents Jest from running in parallel (not great for debugging)
- running Jest from the node_modules directory was necessary in my environment to properly connect to the node debugger. This might vary depending on your environment.

Serious Jest: Making Sense of Hoisting

Jordan Los — Tue, 24 May 2022 19:16:37 +0000

“The ticket’s almost done, I just need to write a few tests”
Later . . .

Hoisting Isn’t Always Hoisting

Even if you’re using Jest, you may not have thought too much about how Jest actually replaces your module with a mock. At least until you’re mocks don’t work.

Jest creates mocks through a process they refer to as hoisting. If you’ve used Javascript long enough you might assume you know what that means. But something I haven't seen elsewhere hoisting in Jest and hoisting in Javascript isn’t the same thing. In this article, I’ll explain both types of hoisting and walk through what happens each time your run a test.

Upcoming

Four ways we might mock a component
Jest Hoisting is Execution Order Manipulation
Javascript Hoisting is Reference Assignment Manipulation
Six Stages of Running a test
Four ways to mock a component revisited

Four Ways We Might Mock A Component

For the sake of example, we’ll make a component called MoviePoster. Take a look at it below:



// MoviePoster.jsx
import { useDolphLundgren } from "ThunderGunExpress";
export function MoviePoster() {
    const ThunderGun = useDolphLundgren();
    return (
        <PosterContent>
          <ThunderGun />
        </PosterContent>
    )
}

// MoviePoster.test.jsx
import { useDolphLundgren } from "ThunderGunExpress";
describe("HomePage", () => {
    it("Should not hesistate", () => {
      // ... 
    });
});

MoviePoster uses ThunderGunExpress to make an API call through a hook called useDolphLundgren. useDolphLundgren, returns a component we can pass as a child to a PosterContent. But our test suite can’t reproduce the output from the useDolphLundgren hook so we'll need to mock it. Let’s look at some ways in which we might mock that hook.

Jest Best Guess

Let’s look at four examples of how we might mock out useDolphLundgren using Jest’s factory mocks. Take a look at each example, guess whether it will work, and then guess why

Ex 1: Inline mock



jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: () => <></>,
}));

Ex 2: Passing a function declaration



function MockHook(props) {
    return <></>
};
jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: MockHook,
}));

Ex 3: Passing a function expression



const MockHook = (props) => {
    return <></>
};
jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: MockHook,
}));

Ex 4: Calling a function expression within another function expression



const MockHook = (props) => {
    return <></>
};
jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: () => MockHook(),
}));

Jest Best Guess Addressed

Example 1 fails with an error telling you that you can’t rely on that fragment you’ve imported to exist.

Example 2 works because the function definition is hoisted and exists when the useDolphLundgren mock gets created.

Example 3 fails because the MockHook variable is undefined when the mock function is created.

Example 4 works because the function expression calling MockHook() isn’t evaluated until it's invoked and at that time MockHook has been initialized.

And there you have it, Jest mocks demystified. Thanks for reading and remember to . . . oh, it's not clear why those work? Are you the type to get upset when you see a library as an answer to a StackOverflow question?

Before we can dig into what Jest is doing with these mocks we need to understand a bit about how Jest and Javascript actually run code.

Hoisting in Jest is Execution Order Manipulation

The Jest docs say Jest creates mocks through hoisting. But what Jest is doing is manipulating the code execution order. The Jest testing finds those mock() calls in a file and execute them before any of the import statements. So it doesn’t matter where you put your mock in a test file, Jest will “hoist” it above the import statements.

Hoisting in Javascript is Reference Assignment Manipulation

So while Jest actually changes the order your code runs, Javascript doesn’t. Hoisting is what the Javascript engine does before executing any code at all. The Javascript engine first runs through your code to create what's called an Execution Context. The process of creating an execution context is beyond the scope of this article, but I’ll review the relevant parts.

Javascript Execution Context Summary

The Javascript engine runs your code twice, creating an Execution Context from it and then executing it
The Execution Context has an identifier for every variable, function, and class
During the creation phase, the Javascript engine only assigns references in memory to function declarations and classes. It leaves everything else undefined
Function expressions differ from function declarations because function expressions are (1) undefined until you initialize them and (2) evaluated only when you invoke them

In other words, hoisting in Javascript means some variables get references to objects in memory before code execution happens.

Javascript Execution Context In-Depth

The Execution Context is a stack frame that gets created every time you call a function. During the creation stage, the Javascript engine runs through your code, grabs all the variables, functions, and classes, puts their name at the top of the scope (we'll call these names identifiers) and does things with them. What things the engine does depends on what it's looking at.

If the engine finds a class or function declaration, it takes the definition, adds it to the heap, and then points the identifier to that definition in memory. I.e. each identifier gets a reference to the definition.

If the engine finds a variable, it marks it undefined and moves on. It doesn’t matter if you defined the variable with var, const, or let because the Javascript engine still leaves them undefined.

Function expressions are like variables with an extra step: the function body isn’t evaluated until you invoke the function expression. We’ll cover this in more detail later.

After creating the execution context, the engine does a second pass on your code and evaluates it line by line. Look at the examples below to see how the Execution Context (EC) influences the output of our code:



// Variable isn't declared, so doesn't exist at all in the EC
console.log(needsDeclaration)

// Variable declared, but left undefined in the EC during creation phase
console.log(needsInitialization)
var needsInitialization = 5;

// Function defintion assigned during the creation phase, so you can call it before defining it
hoistedFoo()
function hoistedFoo(){...}

// Function expressions are just like variables, they are undefined until initialized
unhoistedBar()
var unhoistedBar = () => {...}

// Const and let are the same as var, but will raise an error to avoid accessing an undefined variable
console.log(alsoNeedsInitialization)
const alsoNeedsInitialization = 5

To recap, Jest hoists mock() statements by manipulating the execution order, while Javascript hoists memory allocation by manipulating when it assigns references. The tricky part is that both of these ‘hoistings’ happen when you run a test: Javascript will manipulate your references during the creation phase, and then during the execution phase Jest will manipulate the order your code executes in.

Six Stages of Running A Jest Test

Stage 0: Javascript creation phase runs and sets up the Execution Context

Stage 1: Mocks are executed

Jest finds the jest.mock() calls and invokes those functions before the import statements occur.
Mocks are created during this stage, but the function expression’s passed to mock() are not yet evaluated.
This is happening during the Javascript engine’s execution phase, not its creation phase.

Stage 2: Import Calls are executed

Jest works down the component tree of each import statement before moving on to the next.
If Jest finds a mock, it will import that instead of the module.
The factory expression you passed to mock()gets evaluated here. Whatever is in the Execution Context at this stage is what gets used for that factory expression.

Stage 3: Jest collects the blocks, but doesn't execute them

Jest runs through the describe and it blocks in your test, but it doesn’t evaluate the function expressions you passed in.

Stage 4: Javascript executes the rest of the file

Whatever is defined below the describe and it blocks gets evaluated. This means the Execution Context your tests run in can be updated after the tests are written

Stage 5: Jest runs the tests

Revisiting the Examples

Now that we've covered beginning to end what happens when we run a test file, let's revisit the original examples. I’ll include the code again to save you from going back up:

Ex 1: Inline mock



jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: () => <></>,
}));

This code raises an error because the mock will run during Stage 1 but the fragment would be imported during Stage 2. So Jest raises an error to remind you that the fragment may not exist.

Ex 2: Passing a function declaration



function MockHook(props) {
    return <></>
};
jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: MockHook,
}));

This works because the function definition for MockHook gets added to memory and referenced to the MockHook identifier during Stage 0. When the mock gets created in Stage 1, Jest replaces the module with the function definition referenced by MockHook.

Ex 3: Passing a function expression



const MockHook = (props) => {
    return <></>
};
jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: MockHook,
}));

This fails because Jest is hoisting the call to mock and so MockHook gets moved into the Temporal Dead Zone. The code actually executes like this:



jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: MockHook,
}));

const MockHook = (props) => {
    return <></>
};

Ex 4: Calling the function expression mock within another function expression



const MockHook = (props) => {
    return <></>
};
jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: props => MockHook(props),
}));

Line 5 looks like it should be identical to the same line in Example 3. But there’s a difference in when the variable MockHook is accessed. The timing for when a variable is accessed is subtle enough that it deserves some more attention.

Variable Access Timing

Let’s take Jest out of the equation and dig a little deeper into how function expressions get evaluated.



// needsInitializing is in the Temporal Deadzone
const foo = {
  bar: needsInitializing
}
const needsInitializing = () => console.log("initialized")
foo.bar()

The Javascript engine checks the value of needsInitializing when attempting to assign it to bar during the creation phase. But that means needsInitializing is accessed before it is defined. Compare this to the example below:



// The expression at line 3 isn't evaluated until line 6
const foo = {
  bar: () => needsInitializing()
}
const needsInitializing = () => console.log("initialized")
foo.bar()

This time, the Javascript engine accesses needsInitializing during the execution phase when foo.bar() is invoked. The difference is that during the creation phase Javascript engine doesn’t attempt to evaluate the function expression in line 2 and, so, never tries to access the needsInitializing variable.

Ex 4: One Last Time



// The expression at line 6 isn't evaluated until `useDolphLundgren` is called
const MockHook = () => {
    return <></>
};
jest.mock("ThunderGunExpress", () => ({
    useDolphLundgren: () => MockHook(),
}));

Stage 0: Creation

MockHook is undefined,
(props) => MockHook(props) is unevaluated
MockHook is not accessed.

Stage 1: Mocks executes

Jest moves the execution order of jest.mock() above the const MockHook initialization to mock the useDolphLundgren module.

Stage 2: Import calls executed

Stage 3: Blocks collected

Stage 4: Rest of test file executed

MockHook is initialized

Stage 5: Tests Run

MoviePoster invokes useDolphLundgren() while rendering
Jest gets the mock component from useDolphLundgren
() => MockHook() gets evaluated
MockHook was defined in Stage 4 so the mock gets added.

Stage 6: Success

Use your Javascript skills to impress family and friends

Conclusion

Oftentimes we hit difficulties coding because we make unspoken and inaccurate assumptions. Its easy to assume that Jest and Javascript mean the same thing when they talk about hoisting. Jest, however, uses hoisting to mean manipulating the code execution order and Javascript uses hoisting to mean manipulating when objects in memory get references. I haven't covered how I tested those assumptions though. My first draft did include the steps I used to tease out the information here, but the length grew out of hand. I'll include in a follow up article the process I used to figure out the information here.

About Jobber

We're hiring for remote positions across Canada at all software engineering levels!

If you want to be a part of a collaborative work culture, help small home service businesses scale and create a positive impact on our communities, then visit our careers site to learn more!

Planning for Complexity

Jordan Los — Thu, 17 Feb 2022 16:23:35 +0000

My team recently had to put together a large component for uploading CSVs that had a lot of moving parts. S3 uploads, background workers, GraphQL polling, and real-time progress bars were all involved. The final result looked like this:

The main challenge was how to structure the component so that it was readable, testable, and easy to work with later.

Treat Complexity like Heavy Industry and Zone It Off

Building anything worthwhile will eventually produce some undesirable byproduct. If you want a bustling city of a million-plus people living in sanitary, climate-controlled homes with food, water, and electricity, then you’re going to need a certain amount of heavy industry. But heavy industry produces all sorts of things we don't want near our homes and businesses. Imagine a Sriracha plant going up next door or a waste management facility beside your office. How a city zones for industrial facilities has a significant impact on how you experience that city.

Code may not produce noise and pollution but it does generate a lot of complexity. If we don’t implement some kind of zoning for complex parts of our code, our components may start to feel like a city without land-use regulations. Ultimately, we want strategies for dealing with complexity that keep our interactions with it to a minimum.

Here are four strategies we can use to zone off complexity in larger components:

Declarative State Transitions
Side Effect Containment
Keep Your Return Statement Above the Fold
Descriptive Functions Instead of Comments

Declarative State Enums

Before telling you anything about the ImportCard component from above, see how much you can figure out by just reading the code:

enum UIStates {
  Idle,
  Importing,
  Done,
}

function ImportCard({ initialState = UIStates.Idle }: ImportCardProps) {
  const [uiState, setUIState] = useState<UIStates>(initialState);
  const [workerId, setWorkerId] = useState<string | undefined>();
  const [bannerState, setBannerState] = useState(initialBannerState);

  switch (uiState) {
    case UIStates.Idle:
      return <IdlingCard handleImport={handleImport} />;
    case UIStates.Importing:
      return <ImportingCard onTransition={handleTransitionToDone} workerId={workerId} />;
    case UIStates.Done:
      return <DoneCard showBanners={bannerState} />;
    default:
      assertUnreachable(uiState);
  }

  // I'll show the mutation, handleImport, and handleTransitionToDone a little later in the article.
}

And here are the tests:

describe("ImportCard", () => {
  it("initializes in the idling state", async () => {
    const { getByTestId } = render(<ImportCard />);
    expect(getByTestId("begin-import")).toBeDefined();
  });

  it("transitions to importing state when import is started", async () => {
    const { getByTestId, findByTestId } = render(<ImportCard />);
    fireEvent.click(getByTestId("begin-import"));
    await waitFor(async () => {
      expect(await findByTestId("awaiting-import")).toBeDefined();
    });
  });

  it("transitions to done state when import is completed", async () => {
    const { getByTestId } = render(<ImportCard initialState={UIStates.Importing} />);
    fireEvent.click(getByTestId("awaiting-import"));
    await waitFor(() => {
      expect(getByTestId("done")).toBeDefined();
    });
  });
});

Despite not knowing anything about the underlying components or what kind of problems they might contain, the intent of the ImportCard component is hopefully clear. In fact, if I hadn’t already told you about all the difficulties underneath you might not even know this was a very complicated component. That nice, quiet suburb may be powered by a turbine larger than your house, but that fact never even needs to cross your mind.

Creating Declarative Enums

The first strategy we used was declarative state enums. Declarative state enums involve:

An enum specifying the possible states
A useState hook that initialized with the state enum
A switch statement to return the appropriate components

Declarative enums go a long way in preventing someone from misunderstanding what can happen in your component. And while Typescript's enums aren’t as powerful as the ones in languages like Rust, we can include a little helper function to ensure our switch statement is exhaustive, requiring a case for every value in the enum. This helper function ensures if someone adds another value to the enum, the Typescript compiler will raise an error:

The function definition is this:

function assertUnreachable(arg: never): never {
  throw new Error("Default should be unreachable");
}

and gets used in the switch statement like this:

switch (uiState) {
  // Handle the cases. . .
  default:
    assertUnreachable(uiState);
}

Testing Declarative Enums

Since the ImportCard just swaps between child components, this makes them easy to mock. The mocked components are just a button with a test id and a handler for the state transition function that gets passed down:

// ImportCard.test.tsx

jest.mock(
  "path/to/IdlingCard",
  () => {
    return {
      IdlingCardContent: jest.fn((props: IdlingCardProps) => {
        const mockImport = props.handleImport();
        return <button data-testid="begin-import" onClick={mockImport} />;
      }),
    };
  },
);

I’ll admit the mocked button with a data-testid is a bit of a workaround. A better solution here would be to just have some way to call the handleImport function without worrying about how the subcomponents actually accomplish that task. However, the React Testing Library intentionally doesn’t allow us the ability to directly access a component's props because it wants us to focus on testing visible UI. Normally, testing UI is an excellent strategy. But with high-level components like the ImportCard, testing UI elements too tightly couples the parent component's behaviour with the child component's implementation. A mock button avoids those implementation details and lets us trigger the desired function prop directly.

Another way our tests benefit from using declarative state enums is that we can specify the starting state of our ImportCard. By making the initialState a prop with a default value we can start in a different component state than the default initial state by just specifying it when rendering the component:

const { getByTestId } = render(<ImportCard initialState={UIStates.Importing} />);

Side Effect Containment

S3 uploads, triggering Rails workers, and background polling for progress updates all involve a certain type of complexity called a side effect. If you’re not familiar with the concept of side effects, one way to think of them is this: a function is either returning a value or causing something to happen outside of the function itself. Functions that only return values are simple. Functions that trigger something outside of themselves are not; they are coupled with code you might not control.

But we still want some side effects. What we don't want is for these side effects to be mingled with the rest of our code.

Let's look at how we isolate and zone off the side effects in the ImportingCard:

function ImportingCard({
  workerId,
  onTransition,
}: ImportingCardProps) {
  return (
    <CardContents
      notifications={
        <ImportProgressBar workerId={workerid} nextUIState={onTransition} />
      }
      nextStateButton={<ImportPendingButton />}
    />
  );
}

describe("ImportingCard", () => {
  it("call the nextUIState call when the import is complete", () => {
    const mockOnTransition = jest.fn();
    const { getByTestId } = render(
      <ImportingCard onTransition={mockOnTransition} />,
    );
    getByTestId("import-complete").click();
    expect(mockOnTransition).toHaveBeenCalled();
  });
});

All polling and progress updates can be sealed and tested inside the ImportProgressBar component. CardContents isolates the shared HTML used in each state of the ImportCard. And because ImportProgressBar and the CardContents components have now isolated their complexities from each other, we can mock the ImportProgressBar without worrying about testing anything but the ImportingCard's behaviour.

Keep Your Return Statement Above the Fold

So far we’ve shown how to zone off complexity between components but that same strategy also works within a component.

Print newspapers put the most critical headlines above the fold where interested passersby can see them. Likewise, we can place our most critical sections of code (usually the return statement) near the top of a component. Giving the return statement a place of prominence lets a reader get straight to the point and drill down for details only if they need them.

Take a second look at the ImportCard component below:

enum UIStates {
  Idle,
  Importing,
  Done,
}

function ImportCard({ initialState = UIStates.Idle }: ImportCardProps) {
  const [uiState, setUIState] = useState<UIStates>(initialState);
  const [workerId, setWorkerId] = useState<string | undefined>();
  const [bannerState, setBannerState] = useState(initialBannerState);

  switch (uiState) {
    case UIStates.Idle:
      return <IdlingCard handleImport={handleImport} />;
    case UIStates.Importing:
      return <ImportingCard onTransition={handleTransitionToDone} workerId={workerId} />;
    case UIStates.Done:
      return <DoneCard showBanners={bannerState} />;
    default:
      assertUnreachable(uiState);
  }

  /* As promised */

  const [importItems] = useMutation<ImportItemsMutation>(
    IMPORT_MUTATION,
    {
      onCompleted: importMutationPayload => {
        setWorkerId(importMutationPayload.importItems.workerId);
      },
    },
  );

  function handleTransitionToDone(finalWorkerState: BackgroundWorker) {
    setUIState(UIStates.Done);
    updateBannerOnCompletion(finalWorkerState, setBannerState);
  }

  async function handleImport(uploadUrl: string) {
    await importItems({
      variables: {
        uploadUrl: uploadUrl,
      },
    });
    setUIState(UIStates.Importing);
  }
}

All the component’s logic gets moved “below the fold” into intent-describing functions. Since Javascript uses function declaration hoisting we can use the functions in the return statement before they are defined. This does not, however, apply to function expressions (i.e. arrow functions) which are not hoisted. Arrow functions are a great language feature, but we don't want to force readers to look at the complex parts of our component before seeing our intent.

Descriptive functions instead of comments

Lastly, there are always some lines of code that are complicated, error-prone, and essential. They might involve tricky math, object properties with misleading names, an unintuitive but necessary design choice, or anything non-obvious that makes you feel you should write a comment. Isolate that comment-worthy code into a function describing the intent and move it somewhere else. Spare the readers of your code (including future you) from having to figure out what the code is trying to accomplish by telling them directly.

There weren’t any examples of this in the ImportCard, but comment-worthy code that can be zoned off in a function happens often enough I’ve included it anyway.

Conclusion

Strategies like the ones above often become more valuable after you’ve got something working. Complexity in software, like industrial facilities in cities, occurs because we’re building something big and useful. If we let that complexity operate just anywhere, we expose the rest of our code to problems more often than we need to. But unlike cities, we can choose how to handle complexity after we’ve created it.

About Jobber

We're hiring for remote positions across Canada at all software engineering levels!

If you want to be a part of a collaborative work culture, help small home service businesses scale and create a positive impact on our communities, then visit our careers site to learn more!