DEV Community: GaryBarnes17

9/10 Programmers Make the Same Mistakes

GaryBarnes17 — Fri, 28 Apr 2023 16:00:30 +0000

Introduction

Note: If you are wondering where this title and cover image
came from, it is a reference to the title and cover of 9/10 Climbers Make the Same Mistakes by Dave MacLeod, which heavily inspired this blog post

"I do not think much of a man who is not wiser today than he was yesterday." - Abraham Lincoln

Learning in the Age of Information Overload

As developers, we put a lot of thought into what we want to learn. A quick Google search of “Web Development 2023” will present you with an overwhelming amount of tutorials, lessons, and information about the hottest new tech.

Of course, there is nothing wrong with this. Learning new technologies can be invigorating, and can often add a substantial amount of value to the work you do. However, if we put all of our attention and effort into deciding what we want to learn, we miss the opportunity to examine and change how we learn.

In fact, I would argue that in the long run, how we learn is much, much more important than what we choose to learn. Consider the different frameworks and languages that you were taught in school, the ones that were popular at the beginning of your career, the ones you use now, and the ones you are interested in learning in the upcoming year.

If you think about it, the act of learning is one of the only true constants in our field.

Consequently, I would argue that examining and optimizing how we learn would pay dividends for most developers. In this blog post, I would like to examine a few models for learning, and explain how we can use these to enhance our daily workflow.

It’s Not You, It’s Your System

To make a case for this, I would like to reference Atomic Habits by James Clear (the summary of which can be found here). I’m sure many of you have heard of this, as it is one of the most popular self-improvement books in the past few years.

One of the key points Clear seeks to drive home is powerful effect that small habits we create can have on our lives. He goes on to explain how we can use these small habits to create systems that allow us to achieve our goals. In fact, Clear emphasizes that fact that goals should really be a secondary objective, and we should instead focus on improving our system for achieving them. In the words of the author:

The purpose of setting goals is to win the game. The purpose of building systems is to continue playing the game. True long-term thinking is goal-less thinking. It’s not about any single accomplishment. It is about the cycle of endless refinement and continuous improvement. Ultimately, it is your commitment to the process that will determine your progress.

In the context of our lives as software engineers, the goals may be the particular projects we want to complete, products, we want to launch, frameworks we want to learn, etc. Whereas our “system” is the means by which we accomplish these goals. In this case, I would argue that the system we should be focusing on is the means by which we accumulate knowledge and then synthesize this knowledge to solve unique problems.

With this blog post, I hope to help you optimize this system by taking a look at a few different cognitive models for learning, and referencing some tools you can use to enhance your learning based on the takeaways from these models.

Caveat: this blog post is heavily inspired by the following blog posts from Terry Heick:

Cognitive Load Theory

Image Source

Cognitive Overload Theory Explained

At a high level, the Cognitive Load Theory is a theory built on the idea that the brain can only handle a certain amount of new information while learning. It was developed in 1998 by John Sweller, an educational psychologist at the University of New South Wales. The School of Education published a paper on Cognitive Load Theory in 2017, which provides the following as the definition for Cognitive Load Theory:

Human memory can be divided into long-term and working (short-term) memory
Long term memory is stored in the form of schemas, which are “set of preconceived ideas that your brain uses to perceive and interpret new information” (from Clear blog post)
Processing new information results in a “cognitive load” on the working memory, which can have an effect on how much you are able to effectively learn

So basically, the Cognitive Load Theory tells us that we can only learn so much at once without overloading our working memory.

Why is this important? Well, consider the fact that information processing can be largely divided into two primary activities: knowledge acquisition and problem-solving. Knowledge acquisition is concerned with taking new information in our working memory and creating schemas for it to store in our long term memory.

Problem solving, on the other hand, is concerned with synthesizing unique insights from these schemas to solve the problem at hand. Cognitive overload theory suggests that combining these two activities will ultimately reduce our capacity to do either of them effectively.

With this information, we can infer that the order in which we learn things is rather important. Generally speaking, we should first seek to understand what something is, how it works, and then how we can apply this knowledge to solve new problems (from Terry Heick’s post on this theory).

This is because gaining context surrounding a problem and solving that problem occupy the same mental bandwidth, and doing both at the same time prevents us from doing either well.

What Does This Mean for Me?

With this in mind, imagine that you are assigned a ticket that requires you to update various parts of a web application based on input from a user. The ticket references the potential need to use a state management tool, such as Redux, Recoil, or the Context API, none of which you are familiar with.

While you may be able to find examples in other teams’ codebases that you can copy and adapt, The Cognitive Load Theory suggests that trying to build context for this problem while simultaneously working on solving it will prevent you from doing either well.

Based on this theory, a wiser approach might be to:

Start by understanding what state is in React, what functionality state management libraries seek to add on top of this (without moving into any of the technical details), and why this additional tooling is necessary for the problem you are facing
Then, move on by learning how state works in react, and how to work with the various state management libraries to extend this functionality
Finally, only once you understand the context in which this problem exists and how to use the tools you will need to solve it, focus on applying this knowledge to the particular problem at hand.

While this approach may seem a bit slower, it allows you to understand the reasoning behind a particular tool or approach, and allows you to build an understanding of the problem context before jumping into a solution.

In the long run, this will provide you with a greater understanding of the ecosystem you work with and the tools within it, and free up precious mental bandwidth to focus on solving challenging problems.

Of course, this approach is not limited to solving technical problems. In the blog post I wrote about using Styled-Components, I spent most of my time explaining some of the key concepts of React and how Styled-Components fits into and extends these patterns before I jumped into any of the specific problems this library seeks to solve.

Feedback Loops

Understanding Cognitive Load Theory is particularly helpful for moving from a place of building context within a particular domain to solving a problem within it, but it does not inform us on how we should about solving a particular problem.

To help with this, let’s turn to the concept of feedback loops. According to the definition for feedback loop son Wikipedia, “Feedback occurs when outputs of a system are routed back as inputs as part of a chain of cause-and-effect that forms a circuit or loop”.

In the context of behavior and learning, this means that the outcomes of certain decisions we make are used to influence how we make future decision. In his blog post on Feedback Loops, Terry Heick breaks this loop down in to four distinct steps in the context of learning:

The learner receives input, in the form of either external stimuli or an observation they previously formed
The input is stored as data
The learner analyzes this data, makes observations, and draws conclusions about it
The learner uses these conclusions as input in the context of similar external stimuli in the future to make decisions

I hope you can see how immediately relevant this is to us as software engineers. We write and debug code and the output of this code (i.e. warnings/errors from our linter, syntactic errors, run-time errors, logical errors) informs how we iteratively change it and build upon it in the future.

With that in mind, I would like to focus on two key aspects of feedback loops: cycle time, and the quantity and quality of information that comes from each cycle.

Cycle Time

Put simply, the shorter a feedback loop is, the more effective it is as a learning experience. If we drink coffee before we allow it to cool off, we burn our mouth immediately, and consequently learn to wait until the cup has cooled sufficiently.

However, if we eat loads of unhealthy food, it could take weeks, months, or even years before we see the full set of affects this has on our health. Consequently, it is harder to learn from this feedback loop.

With this in mind, we should take great care to optimize our workflow to be as efficient and streamlined as possible in order to quickly provide feedback, so that we can learn from the mistakes we make while programming.

This idea happens to be what lead to the creation of this blog post. I was talking to a former team member, Kaeden Wile, about how to go about testing and debugging the pipeline for Asurion UI. In order to test our action handles releasing our package to our consuming teams, we were having to wait until a PR was merged in order to update and trigger this workflow. As an alternative, he mentioned that he once forked the Asurion UI repo, and was able to push directly to the main branch in order to get this action to run.

While something likes this takes extra time to configure (especially since you need to comment out all the parts of the action that actually publish something), it pays dividends in the sense that it allows you to test and iterate on your code much, much more quickly.

In order to shorten your own feedback cycles, ask yourself:

Are there any parts of your pipeline that you can shorten or optimize? Are there any actions that are being triggered by some events when they might not need to be? Do you really need to run all my tests on every commit, or can you push these back to run on every push? Are you building our library or project multiple times, and can you optimize this to only happen once?
Do you really need to be running every unit and integration test we have, or can you only run the tests that are relevant to this feature until we are ready to merge? Of great relevance here are the jest -o and --watch flags (documentation here).
If you are building a library, are you able to set up a local sandbox that allows you to quickly pull in a local build and test and changes you have made? Personally, I have a small web-app that points that a local build of Asurion UI, which I use to test any changes I make to the library
Can you alias commands that you repeatedly use? In my local sandbox, I often need to clear out node_modules and point to an updated build of Asurion UI, which I can alias to cd ../asurion-ui && yarn build:core && cd ../sandbox && rm -rf node_modules && yarn && yarn start.
Can you increase the speed at which you type and navigate around in your editor? The faster you can take ideas that come to you and implement them by writing code, the less risk you run of losing some of these ideas. A great resource here for optimizing your use of your tools is the MIT Missing Semester Course.

Finally, consider adopting a more iterative workflow, which Jack Herrington covers in great detail in this video. I highly recommend watching the video, but the key point is that instead of writing all of the code you think is required for a feature and then testing and debugging it, add frequent safety checks along the way.

For example, if you are working on a new section of a page, begin by rendering a “Hello World” div in its place. Then, if this new section needs to hook into some state, make sure you can render the simplest version of that state. Continue to incrementally make the smallest change you can based on the level of risk you are willing to take on.

While this may take longer than writing all of the code at once, it will likely save you time when it comes to debugging and testing. Furthermore, these “safety checks” provide as a good foundation for a refactor in the future, and can serve as inspiration for writing unit tests for this feature.

Quantity and Quality

Just as important as the cycle time of these feedback loops is the information we get from them. It follows that if you have done all you can to optimize the time it takes to complete a feedback loop, you should look to increase the quantity and quality of information you receive from each loop.

I am an avid rock-climber, and in his book titled 9 Out of 10 Climbers Make the Same Mistakes, Dave MacLeod addresses this point directly. He says:

Climbing rock is a fairly short-lived activity… In a three hour bouldering session you might spend less than 30 minutes actually on the wall making moves, and the remaining time resting. Those who spend that resting time with the mind wandering elsewhere or just getting bored waiting for for their body to be ready to climb again… learn to climb slowly and often stop learning altogether. Those who replay the movements of the climb just done, recording which moves felt good or bad and looking back at the holds trying to understand why, and then plan their next attempt to try the movement a subtly different way, progress fast.

As software engineers, we have plenty of downtime in our daily workflow. We have to wait for our pipelines to run, for things to build, for tests to run, we have time in between meetings, we have time in between the launch of an A/B test and the user feedback from it, the list goes on and on.

While this is often a great time to make a cup of coffee or grab a bite to eat, consider using this downtime to proactively address the problem at hand.

If you just pushed a change to a feature branch and suspect some tests may fail, try to anticipate which ones might, and the reasons behind this failure. Pull up any documentation you can find on the testing library, as well as documentation that relates to the piece of code you think may be causing this failure.

If you are often confused by the error messages that come from this code that could potentially fail, take some time to read the relevant documentation, familiarize yourself with some of the most common errors, and even find some threads on the internet full of others dealing with these issues.

If you are waiting for reviews from teammates on a pull request, use this time to go over the PR yourself, and proactively add comments to address any areas you think your team might leave feedback. Better yet, take this time to do some dogfooding for the feature you just built.

The point here is that, while cycle times are often fixed, there is almost always something you can do to get more out of each iteration of a feedback cycle by proactively putting yourself in a position to be able to respond quickly and adequately to the outcome of each attempt at solving a problem.

Conclusion

Software Engineering is a uniquely challenging field in the sense that we are expected to always be learning. If we are not actively keeping up with industry trends, it can feel as though we are falling behind. This, coupled with the fact that we are expected to use this knowledge to solve unique problems across many domains underscores the importance of learning to teach ourselves. Through this blog post, I hope I have convinced you of this importance, and have provided a few helpful frameworks for doing this.

Stop, Drop, and Think Before you Program

GaryBarnes17 — Wed, 05 Apr 2023 18:03:03 +0000

A Case for Thinking Before Programming

The content of this post will probably be a bit different than others you have read. While this post is targeted towards developers, my goal isn’t to teach you about a new framework, language, design pattern, etc. Frankly, there are other resources that can do that better than I can.

Furthermore, I feel like us engineers often get caught up in telling ourselves that the trick to becoming better at our job lies in learning more technical skills. We look back at a recent launch, or a failure in production that caused one of our teammates to get paged and tell ourselves “if I had just known a little more about X, Y, and Z, I that wouldn’t have happened”.

While this is true in some cases, it is rarely the whole story. In fact, this narrative we create often allows us to hide behind the idea that we are one more tutorial away from not making critical mistakes anymore when the reality is, we rarely do enough to make the best use of what we know currently.

Therein lies the call to action for this post. If nothing else, I want to convince you that you probably know enough to succeed on whatever feature or product launch you are working on, and that the key to doing so is to formally think through each problem before you actually begin writing any code.

To help with this, I want to talk to you about lessons my team and I have learned and give you a three-part framework to facilitate thinking before programming. I don’t intend for this to be a formal framework. Really, my goal is that for those of you that don’t have any sort of framework you use to think through problems before you begin implementing solutions for them, you at least walk away with something to begin using.

To make a case for this, I would like to reference a quote from Flash Boys by Michael Lewis, which is a book about high-frequency Wall Street Trading (which I discovered from this blog post).

Russians had a reputation for being the best programmers on Wall Street, and Serge thought he knew why: They had been forced to learn to program computers without the luxury of endless computer time. Many years later, when he had plenty of computer time, Serge still wrote out new programs on paper before typing them into the machine. "In Russia, time on the computer was measured in minutes," he said. "When you write a program, you are given a tiny time slot to make it work. Consequently we learned to write the code in ways that minimized the amount of debugging. And so you had to think about it a lot before you committed it to paper.... The ready availability of computer time creates this mode of working where you just have an idea and type it and maybe erase it ten times. Good Russian programmers, they tend to have had that one experience at some time in the past - the experience of limited access to computer time.

Clearly, there is great value in thinking through problems before you begin brainstorming or working through solutions by actually writing code. Thinking before you write code allows you to avoid the numerous complexities brought on by interacting with computers, and having to work through details of implementation while brainstorming a solution. With that, let’s get started with this 3-part framework

Step 1: Fully Define your Problem Domain

Most of the work we do as engineers is oriented around technical problems. While it is temping to jump straight into looking for solutions, doing so is unwise. Often time, people on your team will have different assumptions about the problem you are trying to solve, the current state of the code base, the particular constraints the solution must fall within, etc. People may come up with different solutions, because they are trying to solve different problems.

To avoid this, make sure you and your team fully define and agree upon the context in which this particular problem exists.

Feedback Context

Let me introduce you to our Feedback component, the design for which is above. This component is fairly simple. It allows the user to select and deselect a positive or negative feedback rating. However, the development process for this component was not simple at all. While there were numerous points of failure, the one relevant to this talk lies in the assumptions we made while developing this component.

List Your Assumptions

At a base level, this is a component that takes in user input. Consequently, my team agreed that we should probably develop it using some base-level input element. When I first saw the design for this component, I saw two exclusive values for a single input. With this, my mind went to radio buttons. This would allow the user to select one, but not both, of the values. So, I suggested this to the developer from an external team contributing this component.

By suggesting this, I made the assumption that deselection was not a priority. As it turns out, that assumption was completely false. Deselection was actually something the team consuming this component really wanted to support.

This brings me to my first point for this step: when working on a feature, or advising someone on how to work on a feature, write down, or at the very least explicit state each assumption you are making when you suggest a certain path forward. Then, verify these assumptions with the rest of your team and any stakeholders.

In this case, had I explicitly noted that my suggestion to use a radio button relied on the assumption that deselection was not necessary, the team consuming this component would have been able to assert that this assumption was false.

Run Mini-Experiments

By the time I learned this assumption was false, I had already suggested the contributor use a group of radio buttons. To avoid re-work, I suggested that the contributor add a third, hidden radio button that would automatically be selected when the user clicked on the button that was currently selected. By suggesting this, I made the key assumption that having this third hidden radio button would be accessible, and wouldn’t completely break the screen reader and keyboard navigation we wished to support (more on that here).

As you might expect, I was wrong. Without going into too many technical details, the core problem with this pattern has to do with keeping this button invisible when a user is looking at the screen and navigating with the mouse or keyboard, while keeping it visible to screen readers.

By the time this component had been fully developed by our contributor, I realized addressing these accessibility concerns would take more trouble than re-writing the component, so we starting over and built this component with buttons as the base input.

This brings me to my second point for this step: when you are making a technical assumption that a feature relies on, run mini-experiments to verify this assumption is correct. Had I created a code sandbox with a demo of this pattern, we would have quickly seen that this was not feasible, and saved days of work.

The point of this story is to underscore the importance of enumerating all of your assumptions, verifying these with your team to make sure you are all on the same page, understanding which technical assumptions a feature relies on, and running mini-experiments to verify these before actually developing a feature.

Step 2: Seek to Understand the Range of Potential Solutions

After following the first step we covered above, everyone should agree on the context in which this particular problem exists. This brings us to step number two: list out all potential solutions, seek to understand the trade-offs between them, and decide on one based on your team’s core values.

Modal Context

Let me introduce you to our Modal component, the design of which can be seen above. Before I go any further, I want to point out that most of the information I cover about the Modal is covered in much more detail in this blog post by Kaeden Wile, a former member of Asurion UI who was the feature owner for this component.

The term modal generally refers to a box of content that displays “on top” of the rest of the content on the page, and blocks interaction with the rest of the page until dismissed. The design for ours can be seen above. To understand the multiple variants this Modal can take on, we can take a closer look at its design in Figma.

As you can see, the similarities between the variants of our Modal have to do with the consistent container, dismiss button, and optional call-to-action buttons in the footer. On the other hand, the header can take the form of a hero image, or of text that represents a header (and optionally, a sub-header).

As Kaeden puts it in his blog post, when we are dealing with something simple like our Button component, it is quite easy to expose all of this component’s options and functionality via props. This is not as easy to do with the Modal. This has to do with the variable layout of the Modal, and the fact that it contains nested components.

If we took this standard approach, we would need to have two sets of props that are passed down to each of the call-to-action buttons in the footer, as well as additional props to manage the configuration of these buttons (i.e. if they are present or not).

This leads us to the key problem we faced when building this component: how do we build this modal to be flexible enough to accommodate all of the design variants, while providing sensible default styles and a clean API?

Look for Trade-Offs Inherent to the Problem

This brings me to my first point for this step. When facing a problem like this, start by listing all or some of the possible solutions as a mechanism to understand the trade-offs present in this feature. If you are already aware of some trade-off, start is on either end of the spectrum, then consider the solutions in between.

This is what we did with the Modal. Going into this refactor, we were aware we needed to balance flexibility and adherence to our design system standards. As in, we want to make sure people adhere strictly to our design best practices but also understand that there are edge cases that we will not be aware of until after we build a component, so we need to have some flexibility baked in. We also wanted a clean, easy to use component API.

On one end of this spectrum of adherence and flexibility, we discussed the possibility of exposing options entirely through props, the way our original modal does (as you can see in Storybook here).

On the other end of the spectrum, I suggested that we consider not creating a Modal component at all, but instead creating a series of templates built with Asurion UI components that looked and behaved like a modal. The biggest problem with this solution is that it would not allow us to push updates to this component, and instead would rely on users pulling in updates by copy and pasting the updated template in their existing code.

While not feasible, this suggestion was useful because it made us think about how we could structure our Modal to allow for customization. The consideration of these two solutions lead to the suggestion of a hybrid solution: our Modal component would act as a container, and we would also export various sub-components that were made to be used in the Modal.

This allowed us to make sure everything matched and defaulted to our design out of the box, but also allowed for full customization of both the structure and styles of the component and each sub-component.

Decide Based on Your Team's Core Values

When building the modal, neither of the solutions were inherently better. At this point we had to ask ourselves, what is most important to us? If all solutions are technically feasible, then the decision between them should be guided by your teams core tenets.

In our case, we know some of the things we value most include building components that:

Work out of the box
Adhere to our global design standards
Are flexible enough to support edge cases that were not designed around, but do have design approval
Are easy to use, and enhance our consumers developer experience
Require little overhead/maintenance (i.e. that we can update in the case of an accessibility bug)

As you can see on this table, the Hybrid Composed Components approach is the best at addressing all of these concerns. Consequently, we chose to take this approach, so that we could provide consumers with an easy-to-use component API (based on having to pass less props and configuration options in) with sensible defaults (by exporting sub-components), while allowing them to step out of this completely by styling our sub-components or putting other components in the modal if necessary.

Look for Existing Solutions

Sometimes, the hardest part of a new feature is coming up with a single solution. If this is the case, look to others for inspiration.

Here at Asurion UI, we often refer to other component libraries when we are looking to build out a new component (The Component Gallery is a comprehensive aggregation of Component Libraries). The soluto-private GitHub Organization is also a great place to start.

When you find one, or ideally multiple solutions, explore what each solution chooses to address and ignore. The range of solutions you find may help you discover some inherent trade-off that you were unaware of.

If two examples are implemented in different ways, seek to discover what each solution prioritizes and de-prioritizes. If every solution you find has a relatively similar implementation, this might clue you in on the fact that this is probably the best path forward for you team as well.

While building out the Feedback component, we did not look to see how other teams had built similar components until we had already started implementing the component. When we looked, we only found a few examples that used radio buttons as a base element, while nearly every other solutions used a regular button. Of the solutions that supported deselection, every single one used a button.

Step 3: Write it all Down!

If you have followed this framework up to this point, then you and your team fully understand the problem space you are working in, you have used this shared understanding to enumerate multiple solutions, and you have decided on one of these solutions in accordance with your team’s core values.

The final step to take before actually writing code is to define your starting state, desired ending state, and write down your entire plan of execution.

Icon Context

Let me introduce you to our Icon component (the post-refactor version of the Icon can be found here). At a glance, this component is simple: it accepts a src prop that corresponds to one of the icons available in our “Icon Catalog” and displays the appropriate svg.

However, if you look closer, you’ll see that src can be of type string or of type JSX.element. This is because all of the icons available in our Design Library are not available in our “Icon Catalog”. Basically, we have an "Icon Catalog" that represents a subset of the Icons available in our Design System Library, which is bundled with our package.

The Icons that are not present in this "Icon Catalog" are kept in our CDN. For this reason, if someone wants to use one of these icons outside of the catalog, they need to download the svg from our CDN, and pass the source code for this icon into the src prop.

Some pain points of this setup include:

Passing in a component as a prop is not intuitive, and not a pattern we use anywhere else in our library. Also, it’s hard to document this with Storybook
This is a Leaky Abstraction. If all the icons exist in the same place in our design library, then a consumer should be able to use them in the same way in our component library. An icon is an icon, and they should be able to use all of them in the same way
This Icon Catalog contributes to our bundle size, and adding all the icons from the design library would cause it to grow to an unmanageable size

Clearly, this current setup was not optimum for long term usage.

Define Start and Finished State.

I was the feature owner for this refactor. I am a visual learner, so I often create diagrams when working through a problem. As soon as I started working on this refactor, I created a few diagrams with this tool called Excalidraw in order to explain the current state of this component to my team.

What you are looking at now is a cleaned-up version of those diagrams. The first point for this step is that, when beginning work on a solution, define exactly what the starting state looks like, and exactly what the final state should look like. That is exactly what I did here. The “current” section refers to the starting state, and then “desired” section defines what the ending section could look like, with references to existing solutions.

By doing this, I was able to ensure that everyone agreed on what this refactor was starting with, and exactly how this component should look when we were finished with it. This forces everyone can think declaratively before thinking imperatively.

Write Down a Detailed Plan of Execution

With the start and final states defined, the last step before you can begin coding is to write down your execution plan. The medium doesn’t matter, the important part is that you write down enough info so that if you suddenly had to hand this task over to another engineer on your team, you would be able to do so with minimal transition time.

What this forces you to do is take a final pass over everything before you start implementing the solution, and serves as a final safety check to make sure you have all of your bases covered. Furthermore, writing down this execution plan allows you to decrease the cognitive load with which you enter a programming task, which in turn gives you more space to think about what you are building.

As a final note, I am sure most of us are familiar with rubber ducky debugging. The screenshots above are from an April Fool's joke by Stack Overflow in 2018 that created a virtual rubber duck (more on that here) If not, the general procedure is that you debug code line-by-line by explaining what your code should be doing, and what it is actually doing to an inanimate object, like a rubber duck.

The premise here is that teaching something to someone else requires a deeper understanding than just learning it yourself, and requires you to look at the problem from perspectives that you may have not yet considered.

You can almost think of writing down this plan of execution as “preemptive rubber ducky debugging”, where you explain all of the steps you will take to a degree that someone else could follow these steps, thereby forcing you do take one more deep look at your plan before getting started.

Your Turn

I would like to end this post the way we started, with a quote. This is a quote from Edsger W. Dijkstra, who you might remember as the computer scientist who came up with the algorithm to find the shortest path between two nodes on a weighted graph. When asked in an interview about how he came up with this algorithm, he had the following to say:

What is the shortest way to travel from Rotterdam to Groningen, in general: from given city to given city. It is the algorithm for the shortest path, which I designed in about twenty minutes. One morning I was shopping in Amsterdam with my young fiancée, and tired, we sat down on the café terrace to drink a cup of coffee and I was just thinking about whether I could do this, and I then designed the algorithm for the shortest path. As I said, it was a twenty-minute invention. In fact, it was published in ’59, three years late. The publication is still readable, it is, in fact, quite nice. One of the reasons that it is so nice was that I designed it without pencil and paper. I learned later that one of the advantages of designing without pencil and paper is that you are almost forced to avoid all avoidable complexities. Eventually that algorithm became, to my great amazement, one of the cornerstones of my fame.
Dijkstra (2001), in an interview with Philip L. Frana. (OH 330; Communications of the ACM 53(8):41–47)"

Through this post, I hope I have convinced you of the value of avoiding “all avoidable complexities” by thinking through a problem, with or without pen and paper, before you even think about spinning up your development environment of choice. Who knows, maybe whatever you create will become one of the cornerstones of your fame.

Enhancing your Developer Experience with Styled-Components

GaryBarnes17 — Sat, 26 Nov 2022 19:16:58 +0000

Intro

Hey everyone, I’m here today to talk about styled-components. If you have never heard of or used styled-components before, that’s great, this talk is for you. If you have used styled-components before, that’s also great, this talk is still for you. There’s always more to learn, and my goal with this talk is for each of you to leave here with the confidence to build and innovate with styled-components.

I am going to make a few assumptions about those of you that are attending this talk. The first is that you are reasonably comfortable with the building blocks of the web - HTML, CSS, and JavaScript. The next is that you have experience with a framework for front end development, specifically React, since styled-components is built for React. However, I am not going to assume you have worked with Typescript in-depth before, nor will I assume that you have worked with the Asurion UI component library, the team that I work on.

Overview

The styled-components library seeks to answer the question - “How can I style my React components?”. When we style our React components with vanilla CSS, we generally do so by giving our components an ID or class name, and then applying styles via class name and/or ID selectors. On the other hand, Styled Components answers this styling question by attaching styles to components directly, and creating new components in the process.

As we go through this talk, I want to focus on two key characteristics of React, which are highlighted in purple in the following diagram:

Decomposing web applications into independent, reusable chunks of logic and markdown called Components
Adapting the behavior of these components based on props

With this first characteristic in mind, we can begin to discuss styled-components.

Map Styles Directly to Components

One of the key value propositions of styled-components is that it allows you to completely remove the mappings between your styles and your React components. When we are working in the React world, we like to decompose a page into components. This paradigm is useful because it allows us to break up logic and markdown into reusable units.

Styled-components allows us to extend this paradigm to our styling as well. Meaning, instead of creating styles with CSS and then assigning these to a particular component, group of components, or group of elements with the various selectors we can use, we wrap each component in its own particular set of styles. If we want to reuse some styles, we can simply reuse the component that these styles wrap. Here is a visual representation of this. On the left, we see that it is possible to give multiple different components the same class name, or have multiple class names (or any other CSS selector) apply to a single component. Styled-components on the other hand ensures a 1:1 mapping of styles to components. Again, on the left we see that styles are applied to an existing component, whereas on the right, styles wrap a component and in turn, create a new component with styles attached.

General Syntax

A simple example is useful here (Code Sandbox). As we go through this and the rest of the examples, please feel free to post any questions in the chat and I will do my best to address them. In this case, we are rendering two sections with the text “Hello World”. One is styled with styled-components, and the other is styled with vanilla CSS. Let me explain briefly what is going on with the styled-components syntax. Consider the title component. Put simply, this chunk of code applies styles to an h1 element. In this case, we generate a Title component by attaching styles to this h1, and then can use this as regular React component. We do the same for the Wrapper component, which is a section element with some styles attached. Compare this to the second example, where we must attach styles via a className selector (of course, we could go about selecting these elements many other ways, such as by element type or by ID). As you can see, the syntax for styled-components is generally of of the following three expressions:

const StyledComponent = styled.element`
    css-property: value
`

const StyledComponent = styled("element")`
    css-property: value
`

const StyledComponent = styled(Component)`
    css-property: value
`

In the most basic example, we attach some styles to an element. This first expression in which we do this is shorthand for the second expression. Regardless of which expression we use, the styled function returns a component with styles attached to it. As you can see in the third expression, you can use the styled method with any custom component (including one from Asurion UI), as long as this component attaches the passed className prop to some element on the DOM. The following snippet is from the Asurion UI Text component, which accepts a className prop and consequently can be styled with styled-components.

// From the Asurion UI Text Component

export const Text = forwardRef<HTMLSpanElement, TextProps>(
  ({ as, size, weight, className, ...rest }, fRef) => (
    <InternalProvider>
      <TextElement
        className={className}
        fontSize={size}
        fontWeight={weight}
        ref={fRef}
        as={as}
        {...rest}
      />
    </InternalProvider>
  )
);

Adapting Styles Based on Props

As I mentioned before, the second characteristic of React that is relevant for this talk is that we often adapt the behavior of components based on the props that are passed into them. This allows us to change how our reusable chunks of code behave based on how the user interacts with them and the current state of the web application. This leads us into another key value proposition of styled-components, which is that it allows us to adapt the style of components based on props. Put simply, a styled-component behaves like a regular React component in that it can accept any number of arbitrary props. When using vanilla CSS, adapting styles of components based on props is tricker and involves conditionally applying a class name, which is harder to read and adds a lot of mental overhead. Consider the following example. I included a snippet here, but have also built out this example in CodeSandbox (Code Sandbox):

const Button = styled.button`
  /* Adapt the colors based on primary prop */
  background: ${props => props.primary ? "palevioletred" : "white"};
  color: ${props => props.primary ? "white" : "palevioletred"};

  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid palevioletred;
  border-radius: 3px;
`;

render(
  <div>
    <Button>Normal</Button>
    <Button primary>Primary</Button>
  </div>
);

In this case, our goal is to create a button with a primary and non-primary variant, which is handled by passing in a primary prop. To keep some consistency between the two examples, I created a Button component that handles this stying with CSS, and a StyledButton component that handles the styling entirely with styled-components. With styled-components, we can keep these styles in one place, and adapt the styles we render in the same way we would adapt the markdown we render in a React Component based on props. On the other hand, if we use vanilla CSS, we must use a ternary operator to conditionally apply a class name based on props. This style must be defined in a separate file, and the inability to adapt a subset of the styles based on props results in duplicated styles. As you can see, this results in higher complexity and greater mental overhead.

What is Styled-Components?

Note: The following diagram and this topic in general is heavily inspired by the info in this video starting at 27:56

Before we dive into more complex examples, I think it is important to establish what exactly styled-components is, and when it should be used. When talking about style libraries, we can generally group libraries into three categories: extensions to CSS, behavior libraries, and style systems. It is important to note that these categories are not mutually exclusive.

Extensions to CSS include solutions such as Tailwind CSS, SASS, and styled-components. These libraries either expand on the syntax of CSS, such as SASS, or let us express CSS styles with a different syntax, such as Tailwind CSS (which uses utility classes) and styled-components, which uses CSS-in-JS, which is basically when you write CSS styles inline with other Javascript code. (Thorough explanation here).

Behavior libraries refer to libraries that seek to ensure components are accessible and behave appropriately. These libraries do not address styling concerns. Examples include React-Aria and Headless-UI.

Style systems refer to libraries that have built-in styles that are exposed to users, and generally restrict users to styling their components within a certain bounds. Examples include Bootstrap and Tailwind UI.

Of course, these groups are not mutually exclusive. For example, styled-components actually allows developers to use a SASS-like syntax via the stylis pre-processor. Additionally, what we refer to as “Component Libraries” generally occupy the space between style systems and behavior libraries. As in, they limit users to styling components within a certain bounds, and they seek to ensure these components behave correctly and are accessible. These component libraries can be built on an extension to CSS, such as styled-components or Tailwind. In fact, it is generally preferable to build these component libraries with one of these extensions. A perfect example here would be our own Asurion UI, which is our component library that is built on top of styled-components.

Why use Styled-Components?

Now that we have established where styled-components fits in regards to other styling solutions, we can begin to talk about why styled-components is my preferred tool for working with styles in React, and why it should be yours too. As I mentioned before, I feel that the biggest advantage to styled-components is that it allows developers to think of styles in the same way they think of components. This is done by effectively making each set of styles a component itself, and by allowing us to conditionally apply certain styling rules based on props.

Another big advantage of using styled components is that it allows developers to decompose a component into independent chunks of style and logic, which makes code much more readable. As you can see with this diagram, we are able to completely separate the logic, structure, and styling of each component. At the bottom of the diagram we have the logic and structure of the component, this handles things like state and lifecycle events. At the top of the diagram we have the styles of the component, which handles, well, styling. The advantage here is that if we have an issue with the styling or logic of a component, we know exactly where to look and reduce the risk of making a change to one that accidentally affects the other.

On top of these developer experience enhancements, styled-components also offers many performance benefits. These include automatic generation of unique class names to prevent overlap or duplication, automatic loading of only the CSS that each page needs, and automatic deletion of unused CSS.

Conclusion

In conclusion, styled-components is a styling library that acts as an extension to CSS by allowing us to express CSS styling rules in Javascript code. Styled-components aligns with React’s core principles by removing the mapping between styles and components and adapting styles based on props, which results in less mental overhead. Styled-components is not an alternative to a component library, but rather, can be used to build one and/or to add styles on top of one. On top of this, one of the most valuable features of styled-components is that it allows us to decompose components into chunks of logic and style. For this reason, it is my preferred styling solution. However, it is important to note it is far from the only solution, I think Tailwind also does a phenomenal job of this decomposition, even if it does fall short in other areas.

Now, let’s move on to a hands-on example...