Rolling Code Standards

Well-documented code guidelines and standards are absolutely critical for creating consistent, cohesive code together. Especially in the context of creating a design system’s component library, it’s crucial to establish consistent API and code conventions to create an excellent user developers’ experience, as well as to make library extension and maintenance easier.

I created the Frontend Guidelines Questionnaire to get frontend teams on the same page when tackling projects together.

In reality, establishing coding guidelines and standards up front is helpful, but it’s unrealistic you’ll get them exactly perfect on Day 1 of a project. Just like everything else in life, change is a constant.

That’s why rolling code standards are helpful. Here’s how it works:

1. At the beginning of the project, get the team together and work through the frontend guidelines questionnaire, filling in whatever you can.
2. Capture your code guidelines, conventions, and standards in a markdown file (CODE-STANDARDS.md or whatever) at the root of your repo or wherever it makes sense (in our latest project, we captured code conventions in our design system’s reference site repo as we employed a style guide-driven process).
3. Work on your project, applying the standards you’ve agreed to. When you inevitably hit a shortcoming or something that isn’t already captured, chat with the team and make a decision on how you want to handle a convention or pattern. Capture that decision in your markdown file and push it.
4. If modifications require changing existing code (“Oh, we actually want to use text="Hello"> of all of our components instead of our current label="Hello">“), tackle those changes as soon as possible to ensure the code base is up to date with the latest standards and a gap doesn’t start opening up between earlier and later work.
5. Enforce and evangelize the new code conventions through code and PR reviews, dev meetings, and however you and the rest of your team(s) communicate.
6. Lather, rinse, repeat. As the project matures, you should find your team touching the code conventions less and less and the dust starts to settle.

Here’s a snapshot of our code conventions file for a big design system project we just wrapped up, which contains over 13 modifications to our code guidelines and standards:

Change is inevitable, and your code standards and guidelines should anticipate that. It’s unrealistic to get everything right on Day 1 of the project, but waiting to document code standards until the end of the project won’t help the team and will almost certainly lead to a messy code base.