Benefits of following styleguides when developing Angular applications
At the end of 2018, Panda-Meetup # 9 Frontend was held in Samara. At this event, I tried myself in a new role and made a presentation. My name is Eugene Kholmov. I came to programming more than 10 years ago as a student. For the last 5 years I have been developing remote service systems in the largest Russian banks, two of them in the position of manager. During this time, I participated in the creation of several leading Russian enterprise-applications, passing through the thorns of heavy architectural, integration and process solutions. Relying on my experience of developing several large Internet banks, I told the guests of the mitap what benefits the following of the rules of good design style gives. The voiced figures impressed the listeners. The meeting participants literally bombarded me with questions. It is possible that this topic will find a lively response among Habr's readers.
Video of my performance can be viewed on Youtube.
And for habrovchan I prepared a text version of his report.
Studying code readability, I came across a curious topic on StackOverflow. It discussed how readable code is important for business, and whether it is more important for performance and correctness. As a result, according to the community members, the readability of the code turned out to be the most important criterion.
At that time I was not interested in the code readability problems - I was developing the next Internet bank. HTML5, AngularJS, LESS were used on the frontend. The project was developed for one of the largest banks in Russia. I switched to this project from Promsvyazbank, where I developed a very similar Internet bank: the same customer segment, the same number of users, and almost the same technology stack (HTML5, AngularJS, SCSS). But, despite the strong similarity of the projects, the transition for me was very difficult. It's all about style. The code of these projects was strikingly different in design and general readability. If the Promsvyazbank developers strictly followed the guidelines, there was no clear style rules in the new project.
It was then that I was able to understand (and even calculate) what benefits a large project brings with a clear adherence to the style guides. After analyzing the costs of improvements on my new project, I came to the same conclusion as StackOverflow readers: readability is the most important criterion.
For AngularJS, and Angular 2+, John Papa, a well-known expert in the world of frontend-development, created the style guides that describe the rules of good style when developing Angular-based applications. Working at Promsvyazbank, I learned about these style guides. The team clearly followed them on all projects. But on the new project, the code got from contractors who hadn’t seriously thought about programming style. With my new team, I faced daily problems that I had once solved before. However, this did not give me any advantage, but only pain and suffering.
There are a lot of rules listed in John Pap's style. It makes no sense to re-list them; they are beautifully set forth in the original source . I will confine myself to just a couple of examples that will colorfully demonstrate the usefulness of the expert’s recommendations.
An example from practice. Internet bank users were shown irrelevant exchange rates. I was assigned the task of ensuring the uploading of current rates at the time of the operation. I expected to see the code responsible for downloading currency rates in services and components. But, of course, he was not there (otherwise I would have nothing to write about). It turned out that currency rates were retrieved and filtered at the start level of the application, in the app.run file, and then placed in Session Storage. This is clearly not the best approach. Besides, all the same, to solve the problem, the code had to be taken out from there. The simple task was gone the whole day.
And now look at the rule Bootstrapping (Style 02-05) from the stylgide.
Place the code that serves to launch the application in a separate file, and do not place the application logic in this file. Logic should be placed in services and components.
As can be seen above, the neglect of just one rule can lead to trouble. But we’ll get really serious consequences if we don’t listen to several recommendations at once.
An example from practice. Our team received the assignment: for utility payments, add the possibility of including in the payment the amount of voluntary insurance. On the frontend part, it came down to a simple task: to place a check-box on the form, the inclusion of which would add to the amount of payment the cost of insurance. In Promsvyazbank we coped with a similar task very quickly. But on the new project, everything went wrong.
Due to the fact that the code of the module of payments was extremely poorly organized, the solution stretched for months. In search of the most suitable option, we postponed this task several times and took it again. And the bank, meanwhile, was experiencing difficulties with payments in favor of utilities. Ultimately, of course, we figured out the problem. But I wondered how much a bad code can cost an organization using the example of such a simple task. I considered how much time all the specialists involved in it had spent on solving the problem. Armed with statistics on average wages. He estimated and rounded the attendant losses. As a result, I came to the conclusion that if there was an initially good code in the payment module, we would save at least 5 million rubles.
Referring to John Papa's style guide, I saw that our module violated several rules of good code at once. Having estimated the degree of influence of each of these rules, I singled out three, the violation of which hampered our work most of all:
Our Internet bank has supported many payments, some of which in their model were completely different from each other. Nevertheless, programmers have tried to make a “universal” payment form that can work with all payment options.
On the form itself, many different blocks were drawn up, which were shown under the same conditions and never showed under others. At the same time, they were served by common logic, which greatly inflated ViewModels.
In the end, all this led to the fact that if something was added in one place, it inevitably fell off in another. At first, it turned out that the choice of the checkbox did not change the amount. We tried to correct the amount field. But it became uneditable on all other types of payments. We tried to replace the amount field with a new one. But the general validation logic fell off: the check box works, but the payment button is not available. Got into a similar situation?
Now let's see what the rule of Rule of One says.
Each individual item, such as a component or service, should be placed in a separate file. You need to make sure that the file does not grow. If the number of lines of code exceeds the magic number 400, this is a sure sign that the component is worth breaking.
When we finished with the form itself, it turned out that functions outside the form stopped working. For example, work with draft payments was damaged. There were errors in the history of operations. And this happened because the model and payment form controller were tied with other components besides the payment form itself. Even worse, the attempt to fix this functionality brought us back to a broken payment form.
We have dealt with the classic case of violation of Single Responsibility. This principle has long been included in the gentleman's recruitment of experienced programmers. And he also strongly recommends using his style guide when developing Angular applications.
Apply single responsibility principle (SRP).
The most inconvenient that you had to deal with is the navigation through the project itself. The logic was scattered across several files, united in an incomprehensible hierarchy of inheritance and delegation. From the names of these files did not follow their purpose. Files lay in different folders. In some folders, for example, Controllers, among dozens of other files, all the time I had to look for those that are needed right now. The number of open tabs in the development environment did not fit on the computer screen and into my head. During debugging, reaching the N-th component, I already forgot which way and why I came here. Periodically it was necessary to carry out full-fledged reverse engineering with the debugger enabled in order to find which project folder contains a file with some specific functionality.
Wise stylgayd knows this problem. To solve it, a group of rules LIFT was created. LIFT is an abbreviation for Locate, Identify, Flat and Try to be DRY. According to the LIFT principles, it is necessary to organize the project structure in such a way that:
The Overall structural guidelines propose to create a folder for each individual component and to group in it all the files related to this component. For example, it is more convenient when the payment-form.controller.js file is not in the Controllers folder, but in the payment-form folder with payment-form.html and payment-form.css.
Folders-by-feature structure recommends creating separate folders with appropriate names for features and project domains. According to this rule, the payment-form folder mentioned above would have to be in the payments folder along with the other components required to work with payments.
As a result, if the authors of the code followed the LIFT-rules, the project structure would look like this:
Agree, this option of organizing the code is much more convenient for the reader. And he would save our entire team a lot of time.
I hope the above examples sounded quite convincingly so that the reader, who had not previously thought about the programming style, had a desire to look into the guideline. In general, well-read and supported code benefits not only the project budget, but also the programmer himself. Readable code easier to review. If you need the help of colleagues, they will penetrate into readable code more quickly. If you are just a novice specialist, then readability of the code is the first thing you need to work on. Even if you write super-correct and perfectly optimized code, but absolutely unreadable and unsupported, in the team you will certainly be respected, but they will no longer be invited to the bar after work.
If this text made you think about something or reminded you of something painfully familiar, I will be glad to see it in the comments to the post.
Video of my performance can be viewed on Youtube.
And for habrovchan I prepared a text version of his report.
Studying code readability, I came across a curious topic on StackOverflow. It discussed how readable code is important for business, and whether it is more important for performance and correctness. As a result, according to the community members, the readability of the code turned out to be the most important criterion.
At that time I was not interested in the code readability problems - I was developing the next Internet bank. HTML5, AngularJS, LESS were used on the frontend. The project was developed for one of the largest banks in Russia. I switched to this project from Promsvyazbank, where I developed a very similar Internet bank: the same customer segment, the same number of users, and almost the same technology stack (HTML5, AngularJS, SCSS). But, despite the strong similarity of the projects, the transition for me was very difficult. It's all about style. The code of these projects was strikingly different in design and general readability. If the Promsvyazbank developers strictly followed the guidelines, there was no clear style rules in the new project.
It was then that I was able to understand (and even calculate) what benefits a large project brings with a clear adherence to the style guides. After analyzing the costs of improvements on my new project, I came to the same conclusion as StackOverflow readers: readability is the most important criterion.
Good style rules
For AngularJS, and Angular 2+, John Papa, a well-known expert in the world of frontend-development, created the style guides that describe the rules of good style when developing Angular-based applications. Working at Promsvyazbank, I learned about these style guides. The team clearly followed them on all projects. But on the new project, the code got from contractors who hadn’t seriously thought about programming style. With my new team, I faced daily problems that I had once solved before. However, this did not give me any advantage, but only pain and suffering.
The tale of lost time or why do we need all these rules
There are a lot of rules listed in John Pap's style. It makes no sense to re-list them; they are beautifully set forth in the original source . I will confine myself to just a couple of examples that will colorfully demonstrate the usefulness of the expert’s recommendations.
Let's start with the simple
An example from practice. Internet bank users were shown irrelevant exchange rates. I was assigned the task of ensuring the uploading of current rates at the time of the operation. I expected to see the code responsible for downloading currency rates in services and components. But, of course, he was not there (otherwise I would have nothing to write about). It turned out that currency rates were retrieved and filtered at the start level of the application, in the app.run file, and then placed in Session Storage. This is clearly not the best approach. Besides, all the same, to solve the problem, the code had to be taken out from there. The simple task was gone the whole day.
And now look at the rule Bootstrapping (Style 02-05) from the stylgide.
Place the code that serves to launch the application in a separate file, and do not place the application logic in this file. Logic should be placed in services and components.
Example per million
As can be seen above, the neglect of just one rule can lead to trouble. But we’ll get really serious consequences if we don’t listen to several recommendations at once.
An example from practice. Our team received the assignment: for utility payments, add the possibility of including in the payment the amount of voluntary insurance. On the frontend part, it came down to a simple task: to place a check-box on the form, the inclusion of which would add to the amount of payment the cost of insurance. In Promsvyazbank we coped with a similar task very quickly. But on the new project, everything went wrong.
Due to the fact that the code of the module of payments was extremely poorly organized, the solution stretched for months. In search of the most suitable option, we postponed this task several times and took it again. And the bank, meanwhile, was experiencing difficulties with payments in favor of utilities. Ultimately, of course, we figured out the problem. But I wondered how much a bad code can cost an organization using the example of such a simple task. I considered how much time all the specialists involved in it had spent on solving the problem. Armed with statistics on average wages. He estimated and rounded the attendant losses. As a result, I came to the conclusion that if there was an initially good code in the payment module, we would save at least 5 million rubles.
Referring to John Papa's style guide, I saw that our module violated several rules of good code at once. Having estimated the degree of influence of each of these rules, I singled out three, the violation of which hampered our work most of all:
- Rule of One - I wrote off 25% of my lost time for breaking this rule;
- Single Responsibility - deviation from this principle contributed to the total loss of 35%;
- LIFT - a violation of this group of approaches, I think, slowed us down the most, 40%.
Rule of one
Our Internet bank has supported many payments, some of which in their model were completely different from each other. Nevertheless, programmers have tried to make a “universal” payment form that can work with all payment options.
On the form itself, many different blocks were drawn up, which were shown under the same conditions and never showed under others. At the same time, they were served by common logic, which greatly inflated ViewModels.
In the end, all this led to the fact that if something was added in one place, it inevitably fell off in another. At first, it turned out that the choice of the checkbox did not change the amount. We tried to correct the amount field. But it became uneditable on all other types of payments. We tried to replace the amount field with a new one. But the general validation logic fell off: the check box works, but the payment button is not available. Got into a similar situation?
Now let's see what the rule of Rule of One says.
Each individual item, such as a component or service, should be placed in a separate file. You need to make sure that the file does not grow. If the number of lines of code exceeds the magic number 400, this is a sure sign that the component is worth breaking.
Single Responsibility
When we finished with the form itself, it turned out that functions outside the form stopped working. For example, work with draft payments was damaged. There were errors in the history of operations. And this happened because the model and payment form controller were tied with other components besides the payment form itself. Even worse, the attempt to fix this functionality brought us back to a broken payment form.
We have dealt with the classic case of violation of Single Responsibility. This principle has long been included in the gentleman's recruitment of experienced programmers. And he also strongly recommends using his style guide when developing Angular applications.
Apply single responsibility principle (SRP).
LIFT
The most inconvenient that you had to deal with is the navigation through the project itself. The logic was scattered across several files, united in an incomprehensible hierarchy of inheritance and delegation. From the names of these files did not follow their purpose. Files lay in different folders. In some folders, for example, Controllers, among dozens of other files, all the time I had to look for those that are needed right now. The number of open tabs in the development environment did not fit on the computer screen and into my head. During debugging, reaching the N-th component, I already forgot which way and why I came here. Periodically it was necessary to carry out full-fledged reverse engineering with the debugger enabled in order to find which project folder contains a file with some specific functionality.
Wise stylgayd knows this problem. To solve it, a group of rules LIFT was created. LIFT is an abbreviation for Locate, Identify, Flat and Try to be DRY. According to the LIFT principles, it is necessary to organize the project structure in such a way that:
- it was clear where to place the new components and where to look for existing ones (Locate);
- the purpose of the component by the file name (Identify) was clear;
- it was easy to navigate in the nesting of folders, use for them the most flat structure (Flat);
- try not to repeat your code, but not to the detriment of the other rules (Try to be DRY).
The LIFT approach complements two more rules.
The Overall structural guidelines propose to create a folder for each individual component and to group in it all the files related to this component. For example, it is more convenient when the payment-form.controller.js file is not in the Controllers folder, but in the payment-form folder with payment-form.html and payment-form.css.
Folders-by-feature structure recommends creating separate folders with appropriate names for features and project domains. According to this rule, the payment-form folder mentioned above would have to be in the payments folder along with the other components required to work with payments.
As a result, if the authors of the code followed the LIFT-rules, the project structure would look like this:
Agree, this option of organizing the code is much more convenient for the reader. And he would save our entire team a lot of time.
Good programmers go to the bar
I hope the above examples sounded quite convincingly so that the reader, who had not previously thought about the programming style, had a desire to look into the guideline. In general, well-read and supported code benefits not only the project budget, but also the programmer himself. Readable code easier to review. If you need the help of colleagues, they will penetrate into readable code more quickly. If you are just a novice specialist, then readability of the code is the first thing you need to work on. Even if you write super-correct and perfectly optimized code, but absolutely unreadable and unsupported, in the team you will certainly be respected, but they will no longer be invited to the bar after work.
If this text made you think about something or reminded you of something painfully familiar, I will be glad to see it in the comments to the post.