.svg)
.svg)
The defining characteristic of winning teams is not only rockstar team members. To truly reach a team’s best potential, a team needs unity in spirit, ideology, motivation, and — most importantly — practices.
If there is an established and agreed-upon modus operandi, team members can move together with more momentum, impact, and efficiency as the expectations of the team are clear among all its members.
A good example of this in action is a well-orchestrated basketball team throwing no-look passes to each other.
Core Code Standards
How can we get one step closer to no-look passes within our engineering team?
Last year we put together a code standards document that all members within our team had input into by either direct authorship or peer reviews of other members’ additions. This document is centrally published within our team’s Notion page.
This document is our agreed-upon modus operandi and covers everything from general principles to abide by to general code standards, testing standards, and pull request review guidelines. For context, below you can see a snippet of the table of contents for our current guidelines.
Our code standards document is a public and written declaration of expectations that can be referenced by team members whenever helpful. Our centralized document is an attempt to alleviate the inefficiencies of oral tradition and tribal knowledge that breed naturally in many engineering organizations.
With the use of codified standards, we increase momentum of the team’s output since we bypass the need for explanations and conversations of unwritten rules that the team currently follows. The core code standards can be referenced by team members during the PR review process as well as discussed during team tag-ups to further validate or amend current guidelines.
Finally, uniformity and predictability of code are also positive byproducts of the document.
A Living Document
The set of standards is a living document wherein any members of the team can propose any amendments to the document. Amendments can be officially added to the document if voted in by a majority of the team.
Our team has a weekly tag-up, and one of the agenda items is to go over specific amendment or addition requests to the document. Prior to the meeting, the reviewer will tag team members for review so they can come into the meeting with context on what is attempted to be codified.
Team members will often discuss the pro’s and con’s of the amendments asynchronously over comment threads prior to the tag-up. This engagement increases buy-in from others as they will have an opportunity to reword and rescope portions of the amendment to achieve a comfortable middle-ground.
The goal of the document — to quote our VP of Engineering, John Whitfield — is coming together, not to get things right. Even if some people disagree with a particular section, we’re bought into the idea that following the same standards will make us more effective.
Unknowns
This document is relatively new, and naturally, some unknowns lie ahead. Some unknowns include:
- Will Notion be an adequate platform for a living document? Or would we greater benefit from using Git as our main method of preservation and amendment?
- What is the best amendment voting method? Would it be better as a live, transparent vote or an anonymous vote?
- How can we delineate certain rules without being too pedantic or prescriptive? We would like to provide guidelines but also assume a certain level of reasonableness among the team.
- Should we ensure the widespread adoption of this document among all engineering teams? Or is it better on a per team basis?
Despite all these unknowns, what is most important is that we create a system in which reinforcing feedback loops will increase developer momentum and overall codebase health. If we implement these kinds of checks at the systems level, we can allow engineering teams to do what they are needed to do best: output features!
Getting Started
Initially, when I first took a stab at creating a code standards document, there was simply so much to say at various levels of abstraction. I began writing the document many times on my computer. Each time I would go back and realize that it was written at such a high level that it sounded almost proverbial. I didn’t like the sound of this and also did not think this type of blanket proselytization would be of any practical use to anybody.
Instead of trying to add an overarching thesis to how to approach engineering, it proved markedly more helpful to think of specific instances wherein a codified standard would have improved team momentum and decreased the need for a conversation on the approach. To do this I simply took a walk in the park. Literally. With my voice recorder on, I spoke my thoughts aloud as I recalled various relevant moments. Afterwards, I transcribed all my thoughts into the document and used that as the baseline draft for other teammates to add to and amend. This may not be the best advice for everyone, but it certainly helped me get rolling.
Once you have a document, how can you increase engagement, ownership, and validity of the document? My advice is to look out for opportunities to ask team members to add to the document whenever possible. If there is something someone is struggling with because it is not codified, ask them to add to the core code standards! Not only is it good to codify ambiguities for future reference, it will also increase engagement, ownership, and validity of the document among the team.
Interested in joining a team that is constantly refining processes in a democratic way? We’re hiring!
