DEV Community: Nate Clark

Parting is Such Sweet Sorrow

Nate Clark — Thu, 01 Apr 2021 13:03:08 +0000

This week I gave notice to my work family at ZEAL 😢. I am of equal parts deeply indebted, saddened, and excited to be moving on to another chapter of my career. What a great run these past three short years have been.

Today I reflect on all the clients I have worked with. The vast diversity of work, team compositions, and seemingly impossible projects. And to this day I can't believe I was part of a team that successfully brought to market a clean room toaster. We've helped countless teams achieve their (sometimes lofty) goals all while making the journey pleasurable for everyone involved. That is what you can expect from ZEAL. It is our signature move.

I look back at all the good times we had and only now realize how precious they really were. The balloon animal workshop (this post's header image), the team competitions, the jet boat, the dinner murder mystery to name a few. The unconditional excitement from Trever every standup. The inescapable joy of Adam. The countless swag and care packages. The always on point Dad jokes, the welcomed trolling, and knowing everyone was there to help each other. Not only to be better at our trade, but to become better people.

I will miss all of that dearly when I power down my company laptop that one last time. Thank you all for an awesome ride.

Sincerely,
— Nate

PS. If you're looking for a great place to work, ZEAL is hiring!

Cave Drawings: Emojis and Commit Messages

Nate Clark — Tue, 06 Oct 2020 17:22:33 +0000

Years ago a friend of mine refused to use emojis in text messages because, in his words, "emojis relegate us to being cavemen". Like any good friend I respectfully disagreed and sent the next several text messages composed entirely of emojis. He was not amused.

🖼️ A Picture is Worth a Thousand Words

The oldest forms of recorded history that we've discovered are some cave drawings from ~30,000 BC. To this day they we can observe an ancient buffalo hunt. I like to imagine some hunters huddled around the fire, enjoying the spoils of their hunt, and bragging to each other about how epic the day was.

The drawings provided a medium for them to share their experience with others without having to retell it.

In comparison, the oldest examples of written language were found to be from ~25,000 years later.

Let that soak in for a second.

Pictographs were the de facto method of recording history for 25,000 years.

📩 Commit Clarity

This got my developer brain thinking...

Why can't we use emojis to convey meaning in our commit messages?

To my anti-emoji friend's point, emojis are indeed modern day cave drawings. They illustrate a common meaning without the overhead of having the reader parse written language. I mean it's been baked into our DNA for millennia. Don't believe me? Science says we recognize pictures much faster than words. So why not embrace the shorthand?

🚚 Emoji Commits

Thankfully, I am not the the first person to come to this conclusion. An awesome open source developer by the name of Carlos Cuesta put together a cli tool and visual guide to help match up your commit subject to an emoji. I use his guide almost daily.

🏹 An Example: The Hunt

If those cavemen were to write their cave drawing commits today they may have looked like the following:

Look at those beautiful emojis 💖. Here we're showing the implicit meaning of each emoji for easy comparison. Over time you'll gain a familiarity with them, especially if you use them consistently (see guide).

😤 The Haters

You will run into developers and/or team leads that don't see value in it and/or consider commit subjects to be holy ground.

To those people I ask the following questions...

Do you agree that a well-formed commit subject concisely defines the work included in a given change set?
If so, can you provide a more concise way of illustrating intent?
If so, is it better than a one character emoji?

If you get a solid answer to #3, I would love to hear about it. Until then, I am promoting emojis 💯.

Most brownfield projects are change resistant too, but it doesn't mean your commit history has to be a wall of text at the yawn festival. Do yourself a favor and throw some emojis in there. A little happiness can go a long way.

📘 The Wrap Up

In my opinion, emojis and commit messages are like peanut butter and jelly. They don't have to go together but when they do, oh man are they delicious 😋.

Every coworker I've persuaded to try emoji style commits has found value in them after taking them for a spin. Personally I really enjoy putting emojis on my commits. Not only do they add clarity to commit history, they make me smile every time.

Am I wrong? Agree with me? Got questions? Drop me a line in the comments, leave me a big squishy ♥️ and/or a glitter pooping 🦄.

Today's post was brought to you by VSCode's "move line up/down" shortcut: Option + Up/Down Arrow

Debug as Code

Nate Clark — Fri, 25 Sep 2020 13:43:56 +0000

Long have the days been using console.log to debug JavaScript code. Local or production, front or back end, it just works. In this post I will try to persuade you to try a different approach to debug logging that your future self will be proud of.

Don't get me wrong, I love me some console.log. There is something elegant about its simplicity and portability. Drop it in the browser console or your Node backend and you've got instant insight into the runtime state of your code.

The Problem

While helpful for debugging, console.log statements are noisy.

Almost every JS project I've worked on in recent years has had some sort of linting rule that disallows console.log statements to be checked into the code base. In general, that is a good practice because displaying any non-critical messages in production will bloat logging and introduce a butt-ton of useless noise 🔊.

For example, here is a small console excerpt from ESPN.com 🤮:

I can almost hear the developer's crying and log service budgets overflowing.

The lesson here being that you should avoid committing console.log statements to your code base.

🔴 What about breakpoints?

At this point you might be thinking..

Couldn't we open up the production code in Dev Tools and drop a breakpoint in there?

Kinda but not really. Production code is almost always mangled and minified. In my experience there is a 50/50 chance that source maps of the original code are available.

Let's say for a moment you're lucky and you have source maps. You place a breakpoint exactly where you think a bug originates. More often than not it's only the tip of the iceberg. So then you dive deeper and place another breakpoint. Rinsing and repeating until you find the source of the bug. All the while you are tripping over your own breakpoints, accidentally stepping into jQuery's internals, and losing context along the way.

Keep in mind, breakpoints can only be used in the browser. Backend code is inaccessible in this way. So even if this completely solved the problem for the client it's only half the equation.

There has to be a better way that works on both client and server.

Enter the debug logging package.

👼 Debugging with `debug`

A few years back I stumbled upon debug by Sindre Sorhus (a.k.a the Man of a Thousand npm packages).

The debug library is not your typical logging package. It does not display, record, track, or ship any logs. It is a noop by default. Only when you enable it via an environment variable does it produce anything.

⛺ Setup

import debug from 'debug';

const log = debug("apollo"); // an arbitrary namespace

log("✅ We're cleared for launch"); // log something

Maybe to your surprise, the above code will not log anything. As I mentioned before, we have to turn on debug logging first.

This is done differently depending on your environment.

For example:

On the server: export DEBUG=apollo
In the browser: localStorage.debug = 'apollo'

For simplicity we can assume logging is enabled for the rest of this post.

👾 Namespacing

Continuing with our code above we add another log instance with a different namespace.

import debug from 'debug';

const log = debug("apollo");
const logLaunch = debug("apollo:launch");

log("✅ We're cleared for launch");
logLaunch(`⏳ T-minus 10 seconds`);
// ...waits 10 seconds
logLaunch("🚀 We have lift-off");

That in turn yields the following log messages:

Right away you'll notice we get some nice information here.

Namespaces are colored uniquely to make them easier to differentiate
Each statement is suffixed by the elapsed time between log messages

For what it's worth, you can log objects like console.log too.

log("📨 Form values", { values });

...but wait there's more

🧮 Wildcard Filtering

Remember the environment variable we set to enable logging? The value of that variable can be a wildcard string.

Let me explain with a few examples.

Assuming in the browser we set localStorage.debug to the one of the following:

apollo - only log the apollo namespace
apollo:* - log any namespace starting with apollo:
apollo:*,-*launch* - log any namespace starting with apollo:, excluding any namespaces that contain launch

This proves quite powerful.

💼 A real use case

Imagine you are creating a new React AirScrubber component. Internal to that component you namespace a log instance apollo:air-scrubber. Then as you develop the component you add debug messages throughout. These act as a sort of CliffNotes for your component.

const log = debug("apollo:air-scrubber");
const logInit = debug("apollo:air-scrubber:init");
const logScrub = debug("apollo:air-scrubber:scrub");

const init = (config) => {
  logInit("🗂️ Air scrubber initializing...", { config });
  // Do initialization work...
  logInit("👍 Air scrubber initialized");
};

const isAirQualityLow = () => { ... };

const scrub = () => {
  logScrub("🧽 Scrubbing air...");
  // Do scrub work
  logScrub("🏁 Air scrubbed.");
}

const AirScrubber = () => {
  init();

  if (isAirQualityLow()) {
    log("🚬 Air quality is low. Starting to scrub...");
    scrub();
  }
};

export { AirScrubber };

Fast forward to the future... 💥 a user discovers there's an AirScrubber bug in production.

Don't panic. We have a way to triage that component quickly and precisely.

Here's how:

Open your Dev Tools console

Run the following

localStorage.debug = 'apollo:air-scrubber*';

Interact with the component and now you'll see all the detailed debug logs you wrote during local development without having to rely on source maps, breakpoints, or even our old friend console.log
Receive high fives from your peers and future self

💻 What about server side?

Much like in Dev Tools, we're going to set the DEBUG environment variable on the server to whatever granularity we choose to enabled debug logging. Once we've done that we have to restart the app to pickup the new value and tail the output.

The debug messages will output the same look and feel we saw on the client.

📘 Summary

Using console.log...

Produces all the log messages - all the time
Is noisy and covers up potential issues
Should not be committed to code base

Using debug...

Allows developers to bake in logging without having to worry about bloat in production
Allows for conditional verbosity (log only what you want)
Provides logging granularity to complex systems via namespacing
Displays log messaging with higher readability
Allows us to debug the same way we do in local development
Should be committed to code base

👷‍♂️ Take Action

Next time you find yourself writing console.log, take a moment to consider the value of the messaging.

Will this message help me debug in the future?
Will this help a new hire understand the system in the future?

If the answer is yes to either question, please consider replacing it with a debug log instead.

These debug messages will prove to be invaluable the next time you track down a bug.

Am I wrong? Agree with me? Got questions? Drop me a line in the comments, leave me a big squishy ♥️ and/or a glitter pooping 🦄.

Today's post was brought to you by VSCode's "open focused file in explorer" shortcut: Command + Down Arrow

Developer Dark Arts: Ralpha-sorting

Nate Clark — Mon, 22 Jun 2020 15:40:23 +0000

It is no secret that order helps bring consistency to complex structures. Order allows our brains to consume and recite information because of some pre-established rules. In this installment of Developer Dark Arts I'll explain what ralpha-sorting is and how avoiding it might increase your velocity.

🏗️ Setup

First, let me give you a challenge to get you in the right head space.

In random order, can you list out the letters of the alphabet? How long would it take? How certain would you be that you got it right the first time?

Approach ①: Naive

If you're like me, right around the fourth or fifth letter I start forgetting what letters I've already listed.

Approach ②: Procedural

Ok, let's try this again but this time we write them down as we list them out. F,B,E,A,... and so on. That works sort of. As the list gets longer we find ourselves reading through the existing list to see if the next random letter was already listed before adding.

Approach ③: Front Loading

Let's try a modified approach. We draw out a line of 26 boxes side by side. In each box we place the next random letter, but this time we'll write the letter in the exact box it would be in if I were listing the letters out alphabetically. Using the random order from the last attempt our list would like the following.

[A][B][ ][ ][E][F]...

Using this method we are a little slower to place the letters in the correct box at the beginning, but as our list grows, our time to place the letter decreases. This is because the process of elimination and the fact that our minds subconsciously know the alphabet. If our next letter to add was D, with very little effort we know D goes immediately before E. No longer are we scanning our list for duplicates, we can place each subsequent letter with confidence because we're sorting prior to placement.

🤮 Ralpha-sorting

ralph: verb [slang] To vomit or throw up

Ralpha-sorting is term I've used to explain the opposite (or lack of) alphabetical sorting. It's a collection of words that has no rhyme or reason, as if someone vomited them into existence.

From our exercise above, our first two attempts were essentially ralpha-sorted lists. Neither were particularly enjoyable or quick to accomplish.

Real world ralpha-sorting...

CSS...

.title {
  font-size: 1rem;
  line-height: 1.5;
  background-color: green;
}

JSON...

{
  "taco": "🌮",
  "burrito": "🌯",
  "cheese": "🧀",
  "salsa": "💃"
}

JavaScript...

import { pipe, omit, map, evolve } from 'ramda';

const thing = { y: 'you', no: 'sort', things: '🤷‍♂️' };

HTML...

<button type="submit" data-link="external" aria-label="Checkout" />

As you can see, ralpha-sorting is everywhere. These are usually products of functionality being added over time. The typical, "just append this new thing to the end" additions.

We can do better.

🔠 Alpha-sorting

What if we alpha-sorted everything?

💄 CSS

There has always been and will continue to be a debate of how you should organize css selectors and props. The organizational methods I've seen are positional, visual, alphabetical, preset, or none at all. Of those, only alphabetical has proven to be consistent and transferrable from project to project.

In css, order and specificity matter (the "cascading" part of acronym). A prop that comes later will supersede any references of the same prop before it.

So if order matters, how is it that we can sort things alphabetically? In most cases selectors can't be alpha-sorted effectively. Every css file has its own quirks in terms of how selectors are defined and trying to sort them in any way is futile. It's the wild west and I haven't found a good solution for this. For that reason let us exclude selectors from this sorting discussion.

In terms of css properties, you can safely sort them alphabetically. For example, the ordering of border-color and color has no impact on the end result. So for reasons I've already stated, putting them in alphabetical order makes sense. There are even some linting & formatting tools that can do this for you automatically when you save a file.

`{}` JSON

Not sure there is much of a debate here. Sort your keys alphabetically and move on.

Again, there is automated tooling to do this work for you.

📜 JavaScript

Imports, exports, and object props. Alpha-sort 'em all™️. Of course there are edge cases but you should shoot for this to be the standard.

<insert automated tooling footnote>

📃 HTML

Who's writing plain ole html these days?? A lot of people, that's who. Even if you're writing React, Vue, or Angular, you should be alpha-sorting element attributes. I've seen sorting alternatives like grouping id and class first but the implementation varies between projects. I am not a fan of any pattern that lowers readability for the sake of subjective "importance".

<insert automated tooling footnote>

📕 Conclusion

Still not convinced? You might think I am nit picking, especially since it doesn't impact functionality. I would argue that readability and developer experience are key factors in a product's success. We've all worked with developers who have avoided working on a project because its codebase is a mess. I'm one of them. Why not lower the barrier, even if it is drop in the bucket?

Alpha-sorting is objective
Its linting is enforceable (in most cases)
Its implementation can be automated

In my opinion those points are hard to argue. Why not do our part to standardize on this universal rule? Can we automate away the alpha-sorting debate?

Prettier's of the world, I'm looking at you 🔭 👀.

Am I wrong? Agree with me? Curious which tools I use to automate alpha-sorting? Drop me a line in the comments, leave me a big squishy ♥️ and/or a glitter pooping 🦄.

Today's post was brought to you by VSCode's "go to definition" shortcut: Command+Click

Developer Dark Arts: React Class Components

Nate Clark — Mon, 15 Jun 2020 15:45:25 +0000

As part of the ES2015 release, classes were formally introduced to native JavaScript as syntactic sugar for prototypical inheritance. Object oriented developers everywhere popped champagne and celebrated in the streets. I was not one of those developers.

🌄 The Web Landscape

Coincidentally, this was also the time that the JavaScript community was being introduced to React. A library that unabashedly pushed its way past existing modular library seemingly overnight. React's creators took lessons learned from Angular 1.x, introduced jsx, and taught us it was OK to JS all the things™️. Got JS? Html? Css? Leftover 🍕? Throw it all in there, it'll blend.

🎓 Stay Classy

Classes provided a nice cork board for React to pin their patterns to. What is the recipe for a React class component you ask?

Create a new file
Write a class that extends React.Component
Repeat

Not much to it. Easy peasy one two threezy. This pattern really flattened the curve for developers learning React. Especially those coming from object oriented languages.

Everyone take a moment and wave 👋 hi to their old friend Readability. As with any new framework, adoption is strongly coupled to readability. React's high readability resulted in most code samples being comprised of classes. Hello world, todo app tutorials, learning resources, Stack Overflow, coding videos; classes as far as the eye can see.

🤷‍♂️ So What's the Problem

For the most part, everything was peachy in the beginning. We had well-defined class components. We had modular, testable pieces of functionality. Life was good. However we know all good things must come to an end. As your React project's codebase grows you realize you're having to write a fair amount of boilerplate.

import React from 'react';

const MIN_POWER_TO_TIME_TRAVEL = 1.21;
const MIN_SPEED_TO_TIME_TRAVEL = 88;

class DeLorean extends React.Component {
  constructor() {
    super();
    this.state = { gigawatts: 0 };
  }

  static const MIN_POWER_TO_TIME_TRAVEL = 1.21;
  static const MIN_SPEED_TO_TIME_TRAVEL = 88;

  componentDidUpdate() {
    const { isLightingStriking } = this.props;

    if (isLightingStriking) {
      this.setState({ gigawatts: DeLorean.MIN_POWER_TO_TIME_TRAVEL });
    } else {
      this.setState({ gigawatts: 0 });
    }
  }

  hasEnoughPower(gigawatts) {
    return gigawatts >= DeLorean.MIN_POWER_TO_TIME_TRAVEL;
  }

  hasEnoughSpeed(mph) {
    return mph >= DeLorean.MIN_SPEED_TO_TIME_TRAVEL;
  }

  render() {
    const canTimeTravel =
      this.hasEnoughPower(this.state.gigawatts) &&
      this.hasEnoughSpeed(this.props.mph);

    if (!canTimeTravel) return <span>🚙</span>;

    return (
      <div title="Great Scott!">
        <span>🔥</span>
        <span>
          {gigawatts} GW / {mph} mph
        </span>
        <span>🚙</span>
        <span>🔥</span>
      </div>
    );
  }
}

NOTE: I am fully aware that this component's implementation is not perfect, but it is typical.

Do you see the class ... extends React, constructor, super(), render() lines? These will be needed in every class component you write. My wrists hurt thinking about all the redundant keystrokes. If you don't think lines of code are important, try wrapping your head around a 1000+ line component file. Es no bueno 👎.

Inevitably you will find yourself debugging your new shiny component because it explodes for one reason or another.

Did you forgot to add the constructor method?
Did you call super()?
Should you be using some other lifecycle method?
- componentDidMount
- componentWillMount
- componentRedundantPrefixMethod
- ...or other undocumented/unstable method?
How are you going to test the hasEnoughPower and hasEnoughSpeed methods?
Wtf is static?
Oh no, not "this" again

I realize these all are not necessarily issues with classes, but our React class components aren't as perfect as we first thought.

🎣 Enter Hooks

If we fast forward a few minor versions of React we get a shiny new feature called hooks. One of the key benefits of hooks is that they allow us to leverage all of the component lifecycle methods in functional components. No weird syntax or boilerplate code required.

Here's the hook-ified version of our stainless steel class component...

import React, { useEffect, useState } from 'react';

const MIN_POWER_TO_TIME_TRAVEL = 1.21;
const MIN_SPEED_TO_TIME_TRAVEL = 88;

const hasEnoughPower = (gigawatts) => gigawatts >= MIN_POWER_TO_TIME_TRAVEL;
const hasEnoughSpeed = (mph) => mph >= MIN_SPEED_TO_TIME_TRAVEL;

const DeLorean = ({ isLightingStriking, mph }) => {
  const [gigawatts, setGigawatts] = useState(0);

  useEffect(() => {
    if (isLightningStriking) {
      setGigawatts(MIN_POWER_TO_TIME_TRAVEL);
    } else {
      setGigawatts(0);
    }
  }, [isLightingStriking]);

  const canTimeTravel = hasEnoughPower(gigawatts) && hasEnoughSpeed(mph);

  if (!canTimeTravel) return <span>🚙</span>;

  return (
    <div title="Great Scott!">
      <span>🔥</span>
      <span>
        {gigawatts} GW / {mph} mph
      </span>
      <span>🚙</span>
      <span>🔥</span>
    </div>
  );
};

There's a lot going on here, especially if you haven't used hooks before. I suggest you take a few minutes to skim through React's hook documentation to get familiar if you aren't already.

The key takeaways are:

We can export and test hasEnoughPower and hasEnoughSpeed methods without adding boilerplate¹
We reduced our total lines of code by ~10 (25% less)
No more this keyword
Boilerplate, "I-only-put-this-in-because-it-won't-work-without-it" code is completely removed
We're back to using functional composition in a functional language
Functional components are smaller, more so when minified

¹ I know we could have exported those two methods in the class example, but in my experience this is how I've seen the majority of components implemented. Where everything is a class method and accessed by this

📜 What If I Am Using Typescript?

WARNING: Strong opinions lie ahead...

This post is about increasing readability and writing less code with better test coverage by specifically avoiding the use of classes.

My current opinion of Typescript is that it increases lines of code, reduces velocity, and fully embraces inheritance. It forces OOP patterns into a functional language in exchange for type checking. Hold on, I have to go write some typings... Where was I? Oh yeah, getting lost in context switching 😉.

If you are stuck writing Typescript I'm sorry and I feel for you. I've been there and it was not enjoyable (for me). Stop reading this post as it might tap into the well of stress and development frustration you have tried so hard to ignore.

Now back to our regularly scheduled post...

📐 Exceptions to Every Rule

As of writing, there are still a few places that classes are a necessary evil. These are considered very niche and make up a very small subset of use cases in most projects.

When extending Error into custom errors
When using React's Suspense, classes useful for capturing errors in error boundaries

📔 Where Does this Leave Us?

I hope/speculate that classes will eventually be exiled to outer reaches of the JS community, a la generators. Neat to show off in academia with very few real world use cases.

React is already migrating that way. Don't take my word for it, take a look at their documentation. Their examples are mostly functional components with footnotes for class versions. They've even posted a formal statement that they prefer composition over inheritance (read: functions over classes).

Disagree? Love classes? Spot on? Let me know in the comments below.

Today's post was brought to you by VSCode's "duplicate line(s) above/below" shortcut: Shift+Option+(UpArrow|DownArrow)

Developer Dark Arts: Default Exports

Nate Clark — Mon, 08 Jun 2020 12:35:43 +0000

So you are starting a ✨ shiny new greenfield 🌱 project. Congrats, not many of us get the opportunity to build something from the ground up. The architecture decisions you make today will impact everyone that comes after you. Hopefully, after a little convincing, you'll choose to avoid default exports.

First some background...

The JavaScript Module

In modern JS, you have the ability to compartmentalize functionality into separate files commonly referred to as modules. Each module represents a single unit of work, an entity definition, or a combination of both. Each module has its own lexical scope which is academia's fancy term for variable scoping... which is my fancy term for the concept that things inside a module are not accessible outside of said module. Things being functions, variables, objects, etc. It also keeps your things from polluting the global namespace.

Exporting Things

Wait a second. If things are not accessible outside my module how is it that modules are useful?

This is where the export keyword comes into play. It defines a contract or sort of micro api to anyone who intends on using your module.

Let's say you have authored the greatest coin flip function ever created. Rather than copy/paste it everywhere you need to flip a coin you decide to extract it into a module appropriately called coinFlip. Ya know, to keep your code DRY.

// coinFlip.js
const coinFlip = () => Math.random() < 0.5 ? 'heads' : 'tails';

In order to expose coinFlip to other modules you have an architectural decision to make.

Option 1: The `default` Export

Those of you coming from CommonJS modules might be familiar with the default export pattern. It defines what the default exported functionality is for the module.

// coinFlip.js
const coinFlip = () => Math.random() < 0.5 ? 'heads' : 'tails';

export default coinFlip; // <= default export

This syntax exposes the coinFlip function in a way that allows consumers to import it via an unnamed alias.

// coinFlip.js
const coinFlip = () => Math.random() < 0.5 ? 'heads' : 'tails';

export default coinFlip;

// decisionMaker.js
import coinFlip from './coinFlip';

I say "unnamed" because the name you give imported thing is arbitrary. I could have chosen to import it with any name really.

For example:

// coinFlip.js
const coinFlip = () => Math.random() < 0.5 ? 'heads' : 'tails';

export default coinFlip;

// decisionMaker.js
import aFunctionThatReturnsHeadsOrTails from './coinFlip'; // <= aliased import of a default export

The local name of the imported thing is entirely up to the consumer. An important thing to note here is that there can only be one default export per module.

While not immediately apparent, default exports promote large object exports.

// coinFlip.js
const coinFlip = () => Math.random() < 0.5 ? 'heads' : 'tails';
const deprecatedFunction = () => 42;

const randomizer = {
  coinFlip,
  deprecatedFunction,
};

export default randomizer; // <= default exported object

Seems legit right? I mean this would future proof your default export. Allowing you to add props to the object as you your module grows but it has one major downside. It isn't tree-shakeable. Tree shaking is the process in which consumers of your module transpile and minify their code. Its goal is to remove unused code branches.

Continuing with the above example, when exporting randomizer it cannot be split and dead branches cannot be groomed. Its export is atomic. Consumers get deprecatedFunction regardless if they are using it or not. Effectively bloating your code bundles with potentially dead code. This becomes increasingly important in the browser where file size has a major impact on load times and user experience.

NOTE: Large object exports are a problem regardless of default vs named exports. However default exports are more prone to this tree shaking pitfall because it's incredibly easy to add a prop to an existing exported object. Often times it's more appealing than refactoring to a named export.

Option 2: The Named Export

Ok, so large object exports are bad. What if I have multiple things I need to export from my module?

This is where named exports shine.

Named export syntax is different than default export in that it requires you explicitly name the things you're exporting.

// coinFlip.js
const coinFlip = () => Math.random() < 0.5 ? 'heads' : 'tails';

export { coinFlip }; // <= named export

This syntax exposes the coinFlip function in a way that allows consumers import it via a well-defined name.

// coinFlip.js
const coinFlip = () => Math.random() < 0.5 ? 'heads' : 'tails';

export { coinFlip };

// decisionMaker.js
import { coinFlip } from './coinFlip';

Unlike the default export syntax, you can export as many named exports as you need.

// coinFlip.js
const HEADS = 'heads';
const TAILS = 'tails';
const Result = { HEADS, TAILS };

const coinFlip = () => Math.random() < 0.5 ? Result.HEADS : Result.TAILS;

export { Result, coinFlip };

// decisionMaker.js
import { Result, coinFlip } from './coinFlip';

const result = coinFlip();

if (result === Result.HEADS) {
  console.log('It was heads');
} else {
  console.log('It was tails');
}

What if you don't like the exported name or it is named the same as another local variable? Like the default export, when importing you can alias named exports however you want.

// decisionMaker.js
import { Result as DiceRollResult, diceRoll } from './diceRoll';
import { Result as CoinFlipResult, coinFlip } from './coinFlip';

// ...

Option 3: Mixed Exports

Default and named exports are not mutually exclusive. You could have a module with a default export and named exports.

const HEADS = 'heads';
const TAILS = 'tails';
const Result = { HEADS, TAILS };

const coinFlip = () => Math.random() < 0.5 ? Result.HEADS : Result.TAILS;

export { Result };

export default coinFlip;

You'll most often see these 🦄 unicorns while working on brownfield projects that started with default exports and later added functionality to a module. Since default exports don't allow for multiple exports they added named exports to accommodate. That said, I doubt anyone has ever intended to start a project with this export pattern.

Which Option Should I Choose?

Here are a few of the pros & cons that I've seen

Default Exports

✅ Familiar to devs migrating from legacy CommonJS modules
❌ Leaves naming up to consumers which doesn't enforce any consistent naming conventions
❌ Restricted to a single exported thing per module
❌ Promotes large object export anti-pattern
❌ Makes tree shaking difficult or impossible in some cases
❌ No editor autocomplete/auto-import support

Named Exports

✅ Allows for unlimited exports per module
✅ Forces you to name things at time of writing, not consumption
✅ Allows for easy tree shaking of unused code
✅ Allows for editor autocomplete/auto-import
✅ Safe find/replace refactoring
❌ Forces consumers to use the exported module name (but allows aliasing)
❌ If a named export is poorly named, you may run into a situation where you have to alias the import in every consumer

Mixed Exports

✅ Familiar to devs migrating from legacy CommonJS modules
✅ Allows for unlimited exports per module
❌ Consumers of the module never know if they want the default export or a named export (adds guesswork)
❌ Naming conventions are unclear
❌ Safe find/replace refactoring is close to impossible
❌ Encourages large object exports which lose the benefit of tree shaking

And the Winner is?

🥇 Named Exports

Having navigated through and made changes to code bases from all three options, the code bases with named exports are by far the best option. There isn't any mind mapping required to import a given module or its things. There is nothing to decide when creating a new module. Simply export a named thing and go on with your day. Lastly and arguably the most important gain is readability.

What do you think? What am I missing? Where am I wrong? Let me know about your experience in the comments.

Today's post was brought to you by VSCode's "command palette" shortcut: Command+Shift+p

Developer Dark Arts: Magic Strings

Nate Clark — Wed, 20 May 2020 12:13:42 +0000

In this post I am going to try and explain what magic strings are, why they are bad, and how to refactor them away.

Why do I care?

Throughout your journey as developer you will inevitably find yourself starting out on a new project. Most of the time it is an existing code base that you will have to sift through, maintain, and add features to. This is the best time to identify anti-patterns, in this case magic strings, and offer up some best practices.

What the heck is a "magic" string?

// animalType.js
export const AnimalType = {
  rabbit: "rabbit",
  pigeon: "pigeon",
  snake: "snake",
};

// tricks.js
import { AnimalType } from "./animalType";

const trick = {
  animalType: AnimalType["rabbit"],
  description: `Pull ${AnimalType["rabbit"]} out of hat`,
};

// favorites.js
import { AnimalType } from "./animalType";

const animal = AnimalType.rabbit;

You may have seen code similar to above. Longtime developers might be able to sniff out the code smell. There are a handful of problems. All of are rooted around the magic string "rabbit".

❌ We're using a string to access props on the AnimalType object in some of the places
❌ Re-typing the same string multiple times is error prone
❌ Find & replacing rabbit is error prone because of string vs dot notation uses
❌ Modern editors' autocompletion results are polluted with string values

What qualifies this as a "magic" string you ask? It's magic because of the string value "rabbit".

Let me explain.

A magic string is a string (or number) whose value is seemingly derived out of thin air and is lacking any extra information to understand its origin. Its value is arbitrary. As arbitrary as a rabbit being pulled from a magician's hat.

-- me just now

Why is this bad though?

There are some pitfalls to writing your coding like this.

Let's say for a moment that our dev manager went to a conference recently and brought back some new patterns for your team to implement. One of which is that we upper case all of our type values so they are easier to identify when reading code.

In this case we would update our code to the following:

// animalType.js
export const AnimalType = {
  RABBIT: "RABBIT",
  PIGEON: "PIGEON",
  SNAKE: "SNAKE",
};

// tricks.js
import { AnimalType } from "./animalType";

const trick = {
  animalType: AnimalType["RABBIT"],
  description: `Pull ${AnimalType["RABBIT"]} out of hat`,
};

// favorites.js
import { AnimalType } from "./animalType";

const animal = AnimalType.RABBIT;

Here we update the "rabbit" value to "RABBIT" in a bunch of places. In a real world scenario the "rabbit" string would have to be updated everywhere it is referenced. Every single reference in every file that uses AnimalType. We'd also have to do this for "pigeon" and "snake". Imagine if their values were more common terms like "name" or "type". Good luck find/replacing those. Super gross 🤮.

How can we improve this?

In a perfect world the string "RABBIT" would be defined once.

Let me show you:

// animalType.js
const RABBIT = 'RABBIT';
const PIGEON = 'PIGEON';
const SNAKE = 'SNAKE';

export const AnimalType = {
  RABBIT,
  PIGEON,
  SNAKE,
};

// tricks.js
import { AnimalType } from "./animalType";

const trick = {
  animalType: AnimalType.RABBIT,
  description: `Pull ${AnimalType.RABBIT} out of hat`,
};

// favorites.js
import { AnimalType } from "./animalType";

const animal = AnimalType.RABBIT;

Why is this better?

✅ We've defined our string values in one place with names that are informational
✅ Everywhere you see the RABBIT variable you know that its actual value is an implementation detail. You only care that you're using the appropriate AnimalType.<type>.
✅ The string value for RABBIT is defined once. Need to make a change to its value? Update that single line of code. No more find/replace nightmares.
✅ Modern editors autocomplete AnimalType without polluting the general results

Conclusion

Hopefully I've done a decent job explaining why magic strings are ill-advised and how you can eliminate some of the issues they cause. Follow these guidelines and the you of tomorrow will thank you. Code readability and ease of maintenance for the win.

Today's post was brought to you by VSCode's "remove dead imports and sort" shortcut: Option+Shift+o

Originally posted on ZEAL's blog