Embed code style in an existing project

Probably, any team sooner or later raises the question of creating and approving coding standards. At first glance, the task is quite trivial. But only in the case when it is decided at an early stage in the development of the project. Then developers only need to choose and apply one of the popular standards, and most often this choice is made for them by the framework that they use.

In our case, everything is not so simple. The project we are working on began its life even before much attention was paid to various standards and descriptions of best practices in the development environment. Including, long before the advent of the now popular PSR standards for PHP. For these reasons, the task of standardizing the code was not posed at earlier stages, but now it has appeared to our team as a challenge.

In this publication, we will talk about how we came to understand the need for a single code style, and developed methods for its gradual implementation in a large-scale project. This experience may be of interest to those who do not yet use standardization, but already feel the need for it.

What we have

• Base code (PHP, MySQL, HTML, SCSS, JavaScript), formed over 10 years;
• An unspoken understanding of the general format, which can include:
  - snake_case for the names of variables and functions in the backend;
  - basic formatting rules (indents, spaces, hyphens);
  - Rules for writing sql queries;
  - names of tables and columns;
  - Hungarian notation for variables containing input data.
  These are just a few examples of the nuances that there are so many in every project.

What do we not have?

Formally adopted style, fixed on paper and binding. Perhaps that is why the unwritten format is inconsistent and changes with the passage of time - its “evolution” is easy to track using the version control system.

Problem awareness

At some point, we began to notice that we often discuss code in the context of formatting, and this takes a lot of time. At the same time, the team began to expand actively. Our new colleagues had their own code writing habits and were not familiar with the practices that were established in our team. As a result, their coding style came into conflict with our “unspoken rules”, having a significant impact on productivity.

For example, combining different styles of formatting and using language constructs within a single block of code led to a significant decrease in its readability:

for ($i=0; $i<$num; $i++)
{
    if (in_array($items[$i]['value'],$filtered))
    continue;
    array_push($valid, $items[$i]);
    if(!$items[$i]['in_menu']) continue;
    $in_menu[] = $items[$i];
}

But if the team always has the opportunity to quickly discuss and resolve controversial issues, then when working with third-party developers there are much more difficulties. We involved third-party specialists in the development of the client part, and it was in the front-end code that the greatest variation in styles appeared. For example, in the class name in one block of HTML code, different notations and even different BEM implementations could be combined.

But here is the main difficulty that arose in collaboration with external experts: how to maintain code written using practices and approaches that not all project developers possess?

The inconsistent choice of methodology in the layout and subsequent editing sometimes led to the following:

...

or

...

If in the first case the use of BEM is traced, then in the second case it is generally impossible to understand “what is happening”. In addition, the use of BEM in class names in HTML sometimes did not at all entail advantages in CSS. The class from the first option, containing a description of the nesting of the element, was still described using nested styles in CSS:

.i-article__item .i-article__item__item .i-article__item__item__content {
...
}

How could this happen? An example from experience: a remote typesetter did part of the work, not having time to complete the mobile version of the interface. Another specialist joined the work, adding a new code in his “unique” style. At the next stage, when porting the layout to the dynamic engine, there was a need to quickly correct something, and this was done by the backend developer, who, of course, did not delve into the “subtleties” of the format used by the layout designers.

It became obvious that one of the highest priorities for us was to avoid such discrepancies in the future. Delaying a solution could result in a loss of productivity and an increase in development time. The team finally formed an understanding of the need to approve a single code format.

Decision making

Since the amount of code is measured in hundreds of thousands of lines, it was not possible to find and process all cases of style violation, even using automatic tools. Therefore, we decided to start applying a single style for the new code, while at the same time updating small fragments of the previous code associated with the task being performed.

Next, you should decide on the format itself. It turned out that the team members had significant differences in their views on the “right style”: some preferred camelCase, others insisted on using snake_case in everything, even in client-side JavaScript.

In this case, the developer’s level and background play a big role. As you might have guessed, in the second case we are talking about a backend programmer with a long experience.

Disagreements arose on many points, but in one they agreed unanimously: I do not want to use one of the existing style guides “as is”, you should preserve the unique, albeit not fully designed, style of your project. Therefore, it was decided to document what was used behind the scenes, and to bring unobvious and controversial issues to discussion.

In a fairly short period, we have created our own style guide for php, sql and partially JavaScript code. Next in line were CSS and SCSS.

The largest number of developers, including remote ones, contributed to the formation of CSS code, and CSS is a language that can be said to have different liberties ... It soon became clear that adherence to a common style is possible only with the most clear and detailed description of all the rules, with many examples of how to and should not be done.

The discussion dragged on for a long time, and the team could not at all come to a consensus on a number of points. As a result, for SCSS and CSS, we decided to use a ready-made third-party document with our small corrections.

We used Sass , CSS , and reviewing and agreeing on the amendments took the team no more than 3 hours.

Execution control

To monitor compliance with the adopted rules, we decided to use automatic verification tools. Today, there is a fairly large selection of such tools, many of which work in the format of cloud services and easily integrate with popular code hosting platforms and continuous integration.

The choice fell on SonarQube - a static code analysis platform that supports different programming languages ​​and offers several formats of use, including selfhosted, along with the cloud version (SonarCloud). In addition, there is integration with our CI platform (Teamcity) and the possibility of preliminary verification in the code editor (SonarLint).

The process of installing the system together with the plug-in package took no more than half an hour, integration with Teamcity took just over an hour. We had to form the so-called “quality profiles” - a set of rules for each language used during the test. Otherwise, the result of the analysis would not reflect the real picture.

It took about three hours to set up profiles to our preferences. Interestingly, 3 options are offered for PHP by default: “PSR2”, “Drupal” and the proprietary “Sonar way” - many are likely to be able to use the system “out of the box”.

After installation and configuration, the “moment of truth” came - a test of checking the quality of the code for compliance with the formulated rules. Run the sonar-scanner command and wait. It took about 4 minutes to index files and verify more than 500 thousand lines of code. The analysis result is available in a pretty nice and convenient interface:

The presented result was for us the expected consequence of the introduction of code style and automatic controls at the late stage of project development. In further work with this tool, we will be most interested in indicators in the right part of the screen, highlighted in yellow. This data reflects the analysis of the new code added since the previous assessment.

What's next?

Our goal is to control the quality of the new code and gradually improve the overall statistics presented on the left side of the screen. Within two weeks we will test the system in the field and evaluate the benefits of its implementation. In the next post, we will share the results of testing the system, summarize and talk about the difficulties encountered.

If you had a similar experience with implementing code style, it will be interesting to discuss this in the comments!