Swizec Teller - a geek with a hatswizec.com

Senior Mindset Book

Get promoted, earn a bigger salary, work for top companies

Senior Engineer Mindset cover
Learn more

    If it works together, it lives together

    [name|Friend] when I got my first big LEGO set in the 90's – the legendary LEGO 8880 Super Car – it came in a big black box with a flippable lid, technical schematics, and a bright yellow plastic mold with 14 compartments to sort the 1347 parts before you started building.

    The 14 compartments you're meant to sort the parts into
    The 14 compartments you're meant to sort the parts into

    I must've built that car dozens of times over the years. Such a wonderful little machine. Independent wishbone suspension, 4 wheel steering, gears that shift, V8 engine. An aspiring engineer's dream.

    Finding all the pieces was always the worst part. Sure I eventually memorized my entire LEGO collection and the smaller components remained assembled in those bins, but ugh.

    By the time I got my second big LEGO set in 2020 – the Saturn V – LEGO had changed their strategy. The 1969 pieces came in a big box filled with numbered baggies.

    Swizec Teller writing a Manning book avatarSwizec Teller writing a Manning book@Swizec
    Unreasonably excited for this 🚀
    Tweet media

    Each baggie contains exactly the pieces you need to build one logical step of instructions. Like completing the core of a Saturn V rocket stage, or the full lunar lander.

    There is no organization. Bags contain pieces of all colors, shapes, and sizes. Mechanical pieces mixed with minifigs, polished exterior plates, and large old school bricks. A total mess.

    And it works. You blaze through the instructions never searching for anything. The ~164 pieces from each bag are in plain sight and you pick them out easily.

    Small haystacks are fast to search.

    Use the LEGO small bag principle in code

    The same principle applies to code. When you're building a feature or fixing a bug, you want the smallest possible search area.

    The less code that could impact your work and the closer it is, the faster you can move, and the less context you need to hold in your brain.

    Code organized by kind

    Imagine a webapp organized like the Super Car:

    your-app/
    ├─ frontend
    │ ├─ css/
    │ ├─ javascript/
    │ ├─ html/
    │ ├─ requests/
    ├─ backend/
    │ ├─ types/
    │ ├─ models/
    │ ├─ db_queries/
    │ ├─ controllers/
    │ ├─ routes/
    │ ├─ json_renderers/
    │ ├─ tests/

    Folders neatly organized by the kind of code they contain, files exporting most functions because they need to be used in other files. Or in tests.

    To build a new feature you'll add a file to all these folders. To know how it works, you'll need to hold the context across 11 files all in your head. Or have a large enough monitor to open them side by side.

    Code organized by feature

    Now imagine a webapp organized like the Saturn V:

    your-app/
    ├─ frontend
    │ ├─ account/
    │ ├─ login/
    │ ├─ articles/
    ├─ backend/
    │ ├─ account/
    │ ├─ login/
    │ ├─ articles/

    Frontend and backend have to stay separate because they run on different machines and use different libraries. You might even keep them in separate repositories.

    But look at how quickly you know where to find code related to user login or listing articles. The folder name tells you! An emerging best practice even matches the URL to the folder name. If you know the URL, you know where to find the code.

    The benefits

    Internally each of these can be further split depending on complexity.

    A frontend component can live in one big file that contains styles, data fetching, the HTML structure, and any UI logic. When you're making a change everything is right there in front of you.

    And because it's all in one file, you don't need to export things that are meant to be internal to your component. Reduces confusion over what's internal and what's an interface 😍

    On the backend this approach is modeled as a service architecture. Every module works as a self-contained independent service that runs a business concern. It exposes an interface and keeps its internals hidden. When you work on that feature, you only need to know its own context. When you use it, there's no need to know how it works.

    As a result you have:

    • less code to search through
    • less context to understand
    • fewer files to edit

    And when files get too large, you split within the same directory. That way relevant code stays close and imports make sense. No more import Foo from '../../../../models/...'.

    Cheers,
    ~Swizec

    Did you enjoy this article?

    Published on September 5th, 2022 in Refactoring, Software Engineering, Programming Lessons,

    Senior Mindset Book

    Get promoted, earn a bigger salary, work for top companies

    Learn more

    Have a burning question that you think I can answer? Hit me up on twitter and I'll do my best.

    Who am I and who do I help? I'm Swizec Teller and I turn coders into engineers with "Raw and honest from the heart!" writing. No bullshit. Real insights into the career and skills of a modern software engineer.

    Want to become a true senior engineer? Take ownership, have autonomy, and be a force multiplier on your team. The Senior Engineer Mindset ebook can help 👉 swizec.com/senior-mindset. These are the shifts in mindset that unlocked my career.

    Curious about Serverless and the modern backend? Check out Serverless Handbook, for frontend engineers 👉 ServerlessHandbook.dev

    Want to Stop copy pasting D3 examples and create data visualizations of your own? Learn how to build scalable dataviz React components your whole team can understand with React for Data Visualization

    Want to get my best emails on JavaScript, React, Serverless, Fullstack Web, or Indie Hacking? Check out swizec.com/collections

    Want to brush up on modern JavaScript syntax? Check out my interactive cheatsheet: es6cheatsheet.com

    Did someone amazing share this letter with you? Wonderful! You can sign up for my weekly letters for software engineers on their path to greatness, here: swizec.com/blog

    Want to brush up on your modern JavaScript syntax? Check out my interactive cheatsheet: es6cheatsheet.com

    By the way, just in case no one has told you it yet today: I love and appreciate you for who you are ❤️

    Created by Swizec with ❤️