Practice of creating and implementing a single style guide for a development team

— Variables in the community are usually written this way, and not in different ways. There are such agreements that exist and live.

— Someone has incorrect hyphens in the IDE, and during a merge request it’s not clear what you did right, because the entire document is highlighted in the diff.

— There are no typhints written somewhere.

— Here the variable is specified without a default value.

And so on.

Yes, almost all of this is about style and conventions that you need to know, and in some places it’s even a matter of taste – but we’re talking about a dramatic expansion of the team. And now 3-4 more new developers join the project at once. And again, each of them has their own background, experience and habits.

Of course, they have something in common, since there is only one stack, but there are also a lot of nuances that result in unnecessary discussions during code reviews. And since we all love code reviews and comments in them, we need to do something about it.

What to do?

Surely there are many different ways in which such situations can be resolved and prevented. My recipe is writing a team style guide. Moreover, it is important that the maximum number of developers from the team participate in this process.

Firstly, this is a good opportunity to get to know each other better. Especially when the team works remotely and only recently got together – just like in our recent situation.

Secondly, this is a convenient opportunity to explore expertise, share solutions, listen to explanations, discuss, get new vectors for development and materials for study.

Now let's try to sketch out a rough action plan. We at Tochka have an excellent tool – regular team meetings, which we hold in some kind of CRM with integrated elements of holacracy. The whole team discusses work issues and proposals there. With this tool we will begin to sort everything out.

1. At the next meeting, we start a project and enter introductory notes there. You can start with the name and those responsible. This is necessary for self-organization, supervision and official involvement of the necessary employees in the process.

2. We form the skeleton of the document and discuss it. We start by creating the initial structure. The easiest way to do this is in Google Docs. There, everyone will be able to comment on controversial issues or submit their own materials and points for discussion. This will save time in the next step.

Important point — it is the initiator of this whole movement who must collect the first materials. Then other participants will become more actively involved in the process.

You can find many such guides on the Internet for different stacks. They already have ready-made collections of key points and generally accepted code formatting standards.

After the initial filling, the document is shared with all team members. It collects edits, discusses it in the comments, studies suggestions and additional practices.

In this process, it is extremely important not to be negative and discuss any comments, even if you personally did not like something. We must remember that everyone has a different sense of beauty, as well as a different set of knowledge. The next stage will have to dot all the i’s.

After the first wave of discussion and edits, we let the document sit for a couple of weeks. During this time, you will probably collect excellent feedback, make all the changes, and the document will take a finished form for the final discussion.

3. We discuss the final version on a call – We record with our voice what the team came up with during the discussion in absentia.

Experience shows that such meetings can take a long time. Somewhere it will be painful, somewhere unpleasant, somewhere controversial. Perhaps one call will not be enough – everything is individual. The main thing is to get the first version of your document, which can be implemented in everyday practice.

In our case, the entire process from idea to first release took about a month.

What should be in the document?

1. Basic rules. For example, what coding standards (PSR12 or PER in PHP, PEP8 in Python), auto-formatting and statistical analysis tools will we use.

2. General recommendations for setting up the environment. Here you can write instructions with screenshots and paths, as well as attach the necessary config files. It is also important to indicate which encoding should be used: developers may have different IDEs, and even such aspects need to be unified.

In addition to the previous point, we set line breaks, indentation depth and other points.

3. Name of entities – the next important and large block. It should immediately give examples of what to do and what not to do. General things to remember:

— how to name models, classes, variables, migrations;

— how to name tables in the database;

— in which case camel case, snake case or pascal case;

— rules: where the singular is used, where the plural is used.

4. Code placement rules is also an important block. It can describe where and what to place. In which layers: services, repositories, views.

This way we will begin to control the issues related to the placement of the code.

5. I would also add rules for working in Git: what layers there are in the project, what we call branches, how we resolve conflicts, what review rules the team adopts for itself.

6. Using patterns, practices, tools – and in general everything that the team deems necessary.

What's the result?

We get a guide that all team members have access to. You can make changes and additions to it, and you can refer to it during code reviews. We host it in a repository or Confluence and make it as accessible and visible as possible. Any colleague now knows where to refresh their memory regarding current practices and agreements.

Yes, implementing the guide will take time. We will have to break some habits, unify and standardize development within the team, and maybe even within the company. But it's worth it.

For example, a style guide will save you a lot of time on explanations when a new person joins the team – all you need to do is send a link to the document. And the guide will also save you from unnecessary disputes!

Okay, we’ve written the guide – now let’s imagine how we can expand its effect and what to do with it next.

Automation

“Everything that can be automated must be automated” ©. Let's take my stack, PHP, for example. Various programmers and companies have created many tools to automate code formatting according to predescribed rules – these are so-called autoformatters or linters (in our case, Pint).

Here we use the CI/CD process and integrate automatic code formatting checking into the pipeline. If the formatter finds any errors, the pipeline crashes.

What does this give us? During the review, we stop wasting energy and time on almost all things related to code formatting. The developer who deploys his code can only run what he has written locally and push it clean. Configs for formatters are made publicly available within the team, and everything will be the same for everyone.

After the linter, we use static analyzers (we use Psalm). These are tools that monitor type compliance and help catch bugs. Such tools are also built into the pipeline and fail it if they find errors that the developer did not notice.

Moment with code placement check can also be automated and implemented into the pipeline.

How such scripts work: you write a config in which you indicate what can be placed and where and what cannot be placed. For example, you can use only services in controllers, only services and models in jobs, nothing at all in models, and there should be no business code in views. This way we also get rid of manual work, because if the developer allows himself to relax, his code will not even miss the pipeline.

Automation can be a slow process. There are many factors here: the experience of team members, knowledge and readiness to implement certain tools. In addition, the quality of the project and its openness to innovation are influenced. For example, to run an autoformatter in a pipeline, you first need to run the entire project on all layers. If the project is large, this may take weeks or even months.

Imagine: five developers are cutting new features, branches are constantly merging. While we ran the dev branch through the autoformatter, developers commit there and get conflicts almost out of nowhere. In general, this is a separate big story about which you can make a separate story.

As a conclusion

At the beginning, I mentioned that such style guides are most often needed by small teams during a period of sudden large-scale expansion. This can happen regularly in startups where teams are just starting to build their processes. This style guide, in my opinion, would be a great start.

Will the guide be useful for the current team? For sure. For the same reasons that I mentioned above: simplification and acceleration of code reviews, standardization and automation of part of the development, use of common tools. There will definitely be benefits, as with any other processes that reduce entropy in the team.

Well, if you need examples of style guides, look at ours for PHP – uploaded it to GitHub. And I also added three more links to similar ones, which I see as useful for viewing and studying.