Cover image for Do your team a favour: start writing a styleguide

Do your team a favour: start writing a styleguide

nimmo profile image Nimmo Updated on ・3 min read

My job has many positive aspects, but if you were to ask me what the best part of it was, I wouldn't hesitate to tell you that it's my team. I am fortunate enough to work with a group of individuals who are all, frankly, awesome.

We're made up of people who have differing levels of experience, and have a good balance of people who focus on what we build and people who focus on how we build it, but what strikes me most often is our ability to say "I've got an idea...", and know that it'll be considered.

This has left us in the very fortunate position of having the psychological safety to be able to ask "What do you think of [insert some idea here]?".

To begin with these ideas came when a member of the team had a specific preference for something (by way of a basic example, let's say, formatting of ternaries), which would be discussed and adopted - either outright if everyone was on board, or as a "trial" if there was some doubt - and we've had a good few instances now of not everyone being entirely convinvced when something is proposed, but then evangelising that very thing to other teams after a trial run has proved its worth.

Once we got into the habit of saying "What do you think of this?", we found that everyone just kept on having thoughts and ideas, and would be actively looking for things that other people did too in order to make our codebase as good as possible (and by "good" we tend to mean "understandable" - and by "understandable" we mean "we can teach you our preferred patterns and explain why we prefer them").

In the same way that having your ideas repeatedly shot down will lead you to stop vocalising those ideas (or worse, stop having them at all), having your ideas considered encourages you to have more of them. Apply that to the entire team, and you've got yourself a group of people who are constantly improving, together.

At some point we decided that recording these preferences would be a helpful way to ensure that anyone joining the team could quickly get up to speed, as well as benefiting those of us with less-than-stellar memories (read: me), since we'd be able to easily check anything that had been decided previously. As much as this might sound horribly oppressive, it's worth noting that our styleguide is entirely decided by the team itself, and lives within a GitHub repository so that any member of the team can submit a pull request with updates, and every member of the team can discuss and approve/merge.

This saves us a lot of time reviewing pull requests in our codebase, as there are a lot of things we just don't have to comment on where we ordinarily would. Moreover, there are things we may not ordinarily comment on because they seem "too minor", but we'd waste time deciding whether it was worth saying something, and now that doesn't happen any more either.

It also means that the whole team feels a greater sense of ownership of the code that we write, and this makes a big difference to day-to-day work.

So, with that in mind: When someone on your team has an idea, I urge you consider it. And if you don't already have one, start talking to your team about your own preferences - I'm seriously glad we did.

Mentioned in this post

Psychological safety:

Airbnb's style guide:

Posted on by:

nimmo profile



I'm a software developer based in Newcastle Upon Tyne, England. I've got a wide range of experience in companies of varying sizes and cultures, and in roles of varying degrees of responsibility.


markdown guide