Team conventions and the tooling to enforce them can often be an afterthought on projects. Deciding on conventions for your team takes collaboration and time. Adding the required tooling to enforce them takes more time, so it tends to be something we avoid.
I recently gave two talks digging into this subject and the benefits of actually taking that time. The first was a lightning talk for Portland ReactJS and the second was a full-length talk for Boston ReactJS. This post summarizes those talks. The ideas presented here use React as an example context, but can apply to any project.
When starting a new feature in a React app, we often start by creating a new component. But before any code is written, you need to think through a few things.
Even though creating these files is not complicated, think about how many actions you need to perform every single time you create a component using the structure above. You need to:
Sound like something to automate? Sure does. We’ll come back to that.
Let’s say you finish the implementation of the component, and open a Pull Request. You might encounter feedback like the following:
“Can you add a test for this?”
Sound familiar? It probably does. This happens a lot.
Who (or what) is the source of truth for the way your team creates files? What about the way you write code? Often, this knowledge resides entirely in someone’s head or is non-existent. People tend to copy a file and follow the patterns established within it, but that pattern might not be the latest one. Even worse, it might be a bad example.
Developers work hard to not repeat ourselves in code but we often fail to apply that concept to our daily workflows. If you need to constantly calculate averages of a set of numbers, you might want to make a spreadsheet. Likewise, if you’re continually creating files that follow similar patterns you should look at ways to automate it.
The React community has the concept of Boilerplates and Starter kits to help developers get started quickly. Most of them include a CLI to help you generate new files. The official React website even maintains a list.
When your team decides to take a different approach from a Boilerplate or starter kit, you’re faced with an important decision. Should you fork the project? If you do, just remember:
If you fork a project you are now a maintainer and must keep it up-to-date.
Frontend development is constantly evolving, and some of the more recent changes are focused on “Zero Config”. But alongside this is a realization that the conventions included in these libraries need to be configurable as teams and projects evolve. A good example of this is Create React App and react-app-rewired.
I’d like you think about creating conventions for your team. You’ll likely start from past projects or open source examples, just make sure you’ve had some group discussion and can confidently say “this is how we do things”.
Think about folder structure, file naming, and the way you write the code within the file. Perhaps you want to generate a failing test to enforce actually writing them.
Once you have established patterns, you can determine how to template and automate them.
Generating files using a specified convention saves time, keystrokes, and clicks. But you also save something much more important.
Don’t waste time on low value choices. Yehuda Katz gave a great keynote at Railsconf years ago that illustrates this point well. To sum it up, you can only make a certain number of decisions per day. Think of your ability to make decisions as a cup — you can fill it with many small decisions or a few large ones, but once it’s full, you’re done for the day.
This phenomenon does not only occur in programming. It can happen in any profession that needs to make frequent decisions every day. The best way to make it easier on yourself is to try to reduce the number of decisions you have to make however you can.
The other major reason to leverage generators and form explicit team conventions is for a better developer experience. Your team does this stuff every day, so why not make it as frictionless and enjoyable as possible?
Here are a few of the many benefits you’ll get by taking this approach:
Sound like a win all around? Let’s look at a few ways to implement this approach. You will want to use a CLI to generate files for you, but make sure its easily customizable. Our favorite is Hygen.
In your project folder, initialize it:
Want to get fancy? Prompt users if they want a functional or stateful component and generate accordingly:
Want some starter templates that do this? Check out hygen-CRA.
The tool you use isn’t important, but the process is.
Regardless of the tool you choose, we’ve found co-locating generator templates with project code is best. When team preferences change, your generators can evolve right alongside them.
For example, say your team adopts TypeScript. The developer adding TypeScript support can simply update the generator templates to use TypeScript in the same Pull Request and everyone will generate TypeScript components going forward.
Find and extract conventions for your team by taking note of repetitive patterns. Note that conventions may differ from project to project or team to team within a company. That’s fine!
Eliminate low value choices and focus on the implementation details.
We’ve really loved the productivity boost that customizable generators have given us and the teams we’ve worked with. Next to updating a READMEor adding PR templates, it’s often one of our first contributions to a project. If you want to chat with us about this approach or want us to help you implement it for your team, say hi!
Chris is CTO at Echobind, a full-service agency specializing in custom web and mobile apps. When he’s not helping developers grow or creating amazing things for clients, you’re likely to find him playing music, cycling, or camping.