The practice of creating and implementing a single style guide for the development team

The practice of creating and implementing a single style guide for the development team

Each developer comes to a new team with his own habits, vision and stereotypes about the development process, tools, code design. Involuntarily, he is a little holivarit with his colleagues, standing up for them. This is a natural phenomenon, but sometimes it can be confusing and take up precious time.

Below is a short story about the personal experience of creating and implementing a style guide in small teams in the phase of rapid growth. I do not claim that the approach is ideal: I will simply tell you what can be expected along the way.

Greetings. My name is Kostya Orlov – I am a marathon runner, a musician, and also a backend developer at the fintech company Tochka.

When the whole team is the heroes of the deletion, selfies from the office start claiming to be exclusive

To get to the heart of the matter, I will draw a realistic picture familiar to anyone who has worked in small teams in the growth phase.

Everything according to the classics: to a foreign monastery with its own charter

So we have a project that two or three people have been working on for several years. They are somehow adjusted processes, the code review goes with a bang, no one pays particular attention to the writing style. The code is dying, the product is being built, and in general, everything is more or less difficult, even when there is no written statute in the monastery.

At some point, the company decides to actively develop the product, for which it hires a few more developers, and in an extremely short time – in one or two weeks.

The first to join the team is the handsome guy Harold (let’s call him that). He has 5–10 years of work experience, his habits, his vision of writing code. He read several good books such as “Clean Code” by Martin, a bunch of articles on Habri on the same topic, and at the first code-review he timidly starts writing his comments to old-timers. For example, the following:

— And let’s use only spaces everywhere, not tabs.

— It is customary to write variables in the community like this, and not differently. There are such agreements that exist and live on their own.

— Someone has wrong hyphens in the IDE, and it is not clear what you have done in the merge request, because the entire document is highlighted in the diff.

– Typhints are not written somewhere.

— Here, the variable is specified without a default value.

And so on.

Yes, it’s almost all about style and deals you need to know, and sometimes it’s even taste – but it’s about a dramatic expansion of the team. And now 3-4 new developers join the project together. And again, each of them has their own background, experience and habits.

The boys are not bad, but sometimes they are rude

Of course, they have something in common, because the stack is one, but there are also a lot of nuances that lead to unnecessary discussions during code reviews. And since we all love code reviews and comments in them, something needs to be done about it.

What to do?

There are probably many different ways to solve and prevent the occurrence of such situations. My recipe is to write a team style guide. Moreover, it is important that the maximum number of developers from the team participate in this.

First, this is a good opportunity to get to know each other better. Especially when the team is working remotely and has only recently come together, as in our recent situation.

Secondly, it is an opportunity to share expertise, share solutions, listen to explanations, discuss, get new vectors for development and materials for study.

Now let’s try to outline an exemplary plan of action. We at Tochka have a great tool — regular team meetings, which we hold in a CRM-like system with integrated. elements of holacracy. At them, the whole team discusses work issues and proposals. With this tool, we will begin to arrange everything on the shelves.

1. At the next meeting, we start the project and enter the introductory information there. You can start with the name and those responsible. This is necessary for self-organization, supervision and formal connection to the process of necessary employees.

2. Form the skeleton of the document and discuss. We start by creating the initial structure. The easiest way to do this is in the same Google Docs. There, everyone can comment on controversial points or outline their materials and points for discussion. This will save time in the next step.

This is roughly how we discussed the draft of our style guide

An important point — it is the initiator of this whole movement who must collect the first materials. Then the rest of the participants will be more actively involved in the process.

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

After the initial filling, the document is distributed to all team members. It collects edits, discusses in the comments, studies wishes and additional practices.

In this process, it is very important not to be negative and discuss any comments, even if you personally did not like something. It is necessary to remember that everyone has a different sense of beauty, as well as a set of knowledge. The next step will be to place all the dots above i.

After the first wave of discussion and editing, we let the document stand for several weeks. During this time, you will surely collect excellent feedback, make all the edits, and the document will take on a finished form for the final discussion.

3. We discuss the final option on the bell – we record by voice what the team sketched in the process of absentee discussion.

Practice shows that such meetings can drag on. Somewhere it will be painful, somewhere unpleasant, somewhere controversial. Perhaps one bell will not be enough – everything here is individual. The main thing is to get the first version of your document that can be implemented in everyday practice.

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

What should be in the document?

1. Basic rules. For example, which coding standards (PSR12 or PER in PHP, PEP8 in Python), autoformatting 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 add the necessary config files. It is also important to indicate which coding should be used: developers may have different IDEs and even such points need to be unified.

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

3. Naming of entities – The next important and big block. It should immediately give examples of how it should and should not be done. Of the general things, don’t forget:

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.

An example with the naming of entities from our style guide

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

So we will start to control the moments related to the placement of the code.

5. I would also add the rules of work in Git: what layers are there in the project, what do we call branches, how do we resolve conflicts, what review rules does the team adopt for itself.

6. Use of patterns, practices, tools — and generally everything that the team deems necessary.

One example of general recommendations

What is the result

We receive a guide to which all team members have access. It can be edited and supplemented, and can be referenced during code reviews. We host it in a repository or Confluence and make it as accessible and visible as possible. Each of the colleagues now knows where to refresh their memory regarding current practices and agreements.

This is what our Confluence style guide looks like

Yes, using the guide will take time. It will be necessary 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 explaining when a new person joins the team — it will be enough to send a link to the document. And the guide will get rid of unnecessary disputes!

Well, we wrote 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 should be automated” ©. Take for example my stack – PHP. Various programmers and companies have created many tools for automating code formatting according to predefined rules – these are so-called autoformatters or linters (in our case, Pint).

Here we leverage the CI/CD process and build automatic code formatting checks into the pipeline. If the formatter finds any errors, the pipeline crashes.

What does it give us? At the review, we stop wasting energy and time on almost all things related to code formatting. The developer, who deploys his code, has to run away what he wrote locally and push clean. Configurations for formatters become public within the team, and everyone will be the same.

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

Moment with verification of code placement can also be automated and pipelined.

How such scripts work: you write a config in which you specify what and where you can place and what you can’t. For example, you can use only services in controllers, only services and models in jobs, nothing at all in models, and whirlwinds should not contain any business code. This way we also get rid of manual work, because if the developer allowed himself to relax, his code will not miss even 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, it affects the quality of the project and its openness to innovations. For example, to run the autoformatter in the pipeline, you first need to run the entire project on all layers. If the project is large, it can take weeks or even months.

Imagine: five developers are sawing new features, the branches are constantly merging. As long as the virgin branch is driven through the autoformatter, developers are committed there and receive conflicts almost out of nowhere. In general, this is a separate big story, about which you can make a separate story.

As a conclusion

I mentioned at the beginning that such style guides are often needed by small teams during their sudden large-scale expansion. This can happen regularly in startups where teams are just starting to build their processes. Such a style guide, in my opinion, will be an excellent start.

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

Well, if you need examples of style guides, take a look at our PHP. dropped it on GitHub. And there I added three more links to similar ones that I find useful for viewing and studying.

Related posts