Duck on a bike reading level

+69 +84

Code style as a development standard / Sudo Null IT News

Let's start right away, this is not about brackets. Here we will talk about how our brain works and why the code style helps to ensure the linear development of the project, significantly speeds up the adaptation of new employees and, in general, forms and educates the development culture. I tried to collect in one article several studies and principles on the work of the developer's brain, how programmers read code, and also shared the results of a personal experiment.

Interesting? Welcome under cat.

Hello! My name is Anton, I write backend in ManyChat. We recently hosted a meetup dedicated to PHP development, where I gave a talk about code style as one of the development standards. According to the feedback, he went great to the guests of the event, and we decided to make a transcript of the report on Habr. For those who especially appreciate the effect of personal presence and like to watch videos more than read texts, we had a broadcast, which is still available. You can find it at the link. For those who love longreads, welcome further.

Our brain is a neural network

It’s worth starting with a description of how it works in general and why everything is needed at all, which I will talk about later. Many of you are familiar with the concept of a neural network, or at least heard this phrase, which for several years was almost a symbol of hype in the IT space and marketing. Even now, many companies add "AI based" to their products, like a "Non-GMO" sticker on dumplings. The neural network works on the principle of pattern recognition and is extremely effective when working with homogeneous data. These are images, video, sound, etc. The main thing that has to do with code styling is the principle on which they were built. Perceptrons, the cells of the network, were described as the processes of the brain and laid down long before they could be implemented into a functional, workable and efficient network due to weak computing power. Our brains, although much more powerful, work in a similar way. As a result, a person uses the power of a trained neural network from birth to death, and training goes almost seamlessly.

So we only perceive images. For the brain, there are no texts, sounds and other things - we perceive all this only after decomposition. Roughly speaking, we separate the images “pixel by pixel”, put them in memory, and then, with the help of associative thinking, we recognize various objects. Thanks to this, we can understand whether we should run from a snake or get on a bicycle and press its pedals. Here is a diagram of a standard perceptron that illustrates how objects are classified. For those who are not familiar with the principle of the perceptron, it may look a bit chaotic. But it is thanks to this balancing and weighting scheme that the neural network recognizes patterns quickly and efficiently.

From programming, we can recall the principle of DuckType, when it is considered that if an object swims like a duck, flies like a duck and quacks like a duck, it is a duck. A peculiar approximation of object detection. And for our brain, object recognition happens instantly. Learning is a much longer process. Therefore, this process can be imagined in the same way as teaching a small child who is only learning words. You take an apple, show it and say: "This is an apple." Take another and repeat again: "This is an apple."

And so on until the result is fixed. Green, yellow, red, spherical, elongated, with and without cuttings, black and white. Year after year, the child builds up its base based on empirical knowledge. I think the principle is clear. We do the same thing when we train a neural network. From object to object, or, more precisely, from image to image.

How a programmer reads code

The same thing happens when we work with code. We open the page, study it, decompose it into blocks, identify different parts - easily separate properties from functions, isolation levels of methods and properties, find constants, and so on. We identify all this by blocks, and therefore an important aspect of code styling is to bring all the code to the same look. This is a key factor that characterizes the readability of the code.

Why is this important? Because a programmer spends most of his working time reading code. No direct correlation was found, for the most part it depends on skill, language (for example, Python is built on indentation, and incorrectly structured code simply will not work), code quality, etc. But 50% of the time is spent reading your own and other people's code. If the code is complex, then the indicator can reach 75%, and if the code is really bad, then 95% of the time can be spent on reading and trying to figure out where to add one line to fix some kind of flaw. And now the question. What do you do if you see that your code is spending 75% of its time reading disk or allocating memory to doubly linked lists? The programmer will try to optimize this process, try to change the algorithm, apply a more efficient storage structure, etc. Accordingly, when the time spent became critical, I began to inspect this process. And one could say, well, this is the brain, it is much more powerful than any computer and can store about a petabyte of data. But, in the process of developing my mental framework for working with code (the hidden process of forming code reading habits), I came across studies in which sensors tracked the movements of the eyes of novice and experienced programmers. It all looks like this:0002 Beginner

Experienced

Notice what an experienced programmer does. It extracts blocks of code, decomposes them, and reads them block by block, highlighting key parts and analyzing how they work. The beginner rushes about line by line, just trying to understand what is happening here. The lion's share of time is spent on adding up the big picture and reading the code occurs with constant cross-inspection.

The video is quite old, from 2012, and the recording was aimed at studying the processes of the programmer's brain. You can read a little more here and here.

Now is the time to return to the description of how perceptrons work. This is a visual demonstration of the work of a trained and not trained neural network. Based on their knowledge base, an experienced programmer walks through the code like an interpreter, often without even realizing it. You can approach this problem in the same way as we approach the problems of training neural networks.

There are 2 ways to speed up code reading:

1. Continually build the developer's knowledge base of what the code might look like. This means continuous learning, which constantly increases the power of the network.
2. Bring all code to one standard, set the same code style

Of course, it is quite obvious that the first method is very labor-intensive. In this case, the programmer needs to constantly read the repositories. And given the staff turnover, the emergence of new technologies and practices, this becomes almost impossible. The elimination method remains code styling, which will reduce the affect on decomposition and leave only the affect on business logic.

Number of piano tuners

Imagine that a team of 5 people writes, as they want, in all modules and components of the system, constantly receiving overlapping tasks, correcting each other's code. What is the possible number of possible ways to write the condition in if, given that everyone writes in their own way? 5. And how many valid blocks do we have? All constructions, calls to single-argument and multiple-argument functions, namespaces, classes, traits, interfaces, block positioning, statics, visibility zones, etc. This is assuming that everyone uses only 1 style of writing that is different from the styles of everyone else. What if there are 10 people? And 50? It is clear that with an increase in the number of people, the variance will decrease due to the limited number of ways to write the same block. And this is the first level in which we do not invest one of the main problems of programming - variable naming. The multiplier effect and all possible combinations are not even taken into account. Throw on top of separation style, indent spaces and tabs, love for if noodles, etc. and so on. And new specialists are constantly coming in and old ones are leaving. As a result, you get a huge unreadable code that is impossible to get used to and it is impossible to develop a well-trained neural network from programmers in the company.

Our brain is extremely lazy

Another interesting effect of the work of our central processing unit in the skull is the extremely negative perception of new information. Our brains are lazy. With a mass of about 1.5-2% of the total body weight, the brain consumes 25% of the body's total energy. One of the most resource-intensive operations for the brain was, is and remains the concentration of attention. You can maintain maximum concentration for 20-25 minutes (hello Pomodoro technique), and during this time the brain will gobble up as much glucose as it would gobble up for a whole day of subjective rest. Processing new data is an extremely resource-intensive process. And one of the main goals of the brain is to save these very resources. It has to do with how our mental model works. A kind of psychological blocker. It looks like this. You start learning something new. Something new is hard to come by, and due to the lack of tangible dynamics of progress, your self-esteem begins to decrease due to the thought “I’m stupid!” hovering in the background. Our psyche is arranged in such a way that our entire attitude depends on self-esteem, and our success in society, in turn, depends on our attitude. And in order not to break the basic social lifts on adaptive addictions, our brain begins to resist activities that reduce self-esteem. As a result, you want to watch a TV series, read Habr, go for a coffee, sit in the social. networks, etc. Anything, just not to teach that same Landau field theory. Or fix a hard-to-reproduce bug. Or… read low-quality code that is hard to understand. A great example of how the brain behaves according to a limitation in this area is people in their 70s and 80s who are unwilling to master a smartphone or 2 buttons on a robot vacuum cleaner. Resources are running out. The brain desperately blocks the learning process and acts on the knurled. These resources are plentiful while you are young. With the passage of time and growing up, they become less and less. Works quite linearly. Fortunately, this is offset by the increasing power of our neural networks. If we are not talking about direct targeted degradation, of course.

Some stereotypes

A common misconception you may have heard is “Yeah, I'm a pro, I can read any code. I write fast and cool, solving company problems. It doesn't matter what my code looks like as long as it solves the problem. The rest just can’t figure it out quickly, I don’t have a problem with that.” If there is such a coder in your environment, you can tell him: “Dude, I have bad news for you. You affect the whole team, and this approach is the reason why others write more slowly when a super efficient programmer quickly forces the code.

A super efficient programmer who writes without formatting and standardization is actually super efficient at 2 things:

• Super efficient to close tasks without going into design and style.
• It's super effective to slow down everyone else, because after its additions, people are trying to figure out what happened here for a long time.

Why code style is needed

Although it should already be obvious, but you need to somehow emphasize the main points.
Code style:

1. Provides a linear development of the project and does not affect the size of the code base. If you ensure that the code is written historically, no matter how many developers come and go, you always have the same quality of code, which allows the project to grow dynamically, regardless of its size.

2. Significantly speeds up the onboarding process for new programmers. If your code is written clearly, a new specialist will very quickly train his neural network to identify blocks and begin to be useful. There is such a thing as an employee's payback point. This is the point at which the employee begins to bring only benefits. And if the code is written clearly, new employees do not need to understand business logic, they just need to learn how to read your code. And the sooner he does this, the sooner he will stop asking tons of questions to other specialists, taking up their time. And the time of specialists who have passed the breakeven point is much more expensive for the team and the company in terms of the potential value brought to the product.

3. Removes dependence on particulars. No need to constantly stumble over someone's originality and specific design.

4. Minimizes the mental blocker effect when learning new code. Your brain resists less because no need to delve into someone else's style. It takes much less mental resources to read understandable code.

5. Minimizes reputation losses. Very soon, after arriving at a new company, the programmer will begin to share his impressions with former colleagues and friends. And he will either say that everything is cool here, or highlight the negative points in working with the code. In a sense, this is an HR bonus: if you want cool programmers to work with you, do a good project. Although this is not always important, and in a number of companies they do not look at the quality of the code in principle, but only look at the delivery of features to the sale, this is a nice bonus. It's no secret that a frequent reason for leaving is fatigue from the constant sawing of a low-quality codebase.

6. Forms and nurtures a development culture. The task of a programmer lies at a lower level than the future of the entire company, but it is important to convey the understanding that the understandability and readability of the code now affects the dynamics of further development. If the code is difficult to read and not standardized, refactoring and scaling with pain and suffering, then with the growth of the project code base, the development speed will decrease. The more low-quality code, the more difficult it is to write a new one, the slower the product develops, the more difficult it is for the company to increase its turnover and the more difficult it is for it to pay you more money, because a lot of money is spent on ensuring the life cycle of the project with more and more new employees, which is the main onboarding time is spent not on the benefit of the company, but on the classification of the drugs under which this code was written.

Ideal code

We all understand that it does not exist. From the point of view of the canonical code style is the concept of code design. And everything would be fine if it were true. In long-range development, code style is a broader concept that includes development principles. Breaking code into logically isolated blocks in classes or files is also about styling. Naming, isolation levels, inheritance. All these are tools not only for interaction, but also for designing your complex mechanism, where each brick plays its role.

Concepts change from language to language. Particulars come to the fore. But the foundation remains unchanged. A quality code is determined by only two criteria:

• The code is anonymized
• Code reads like a book

Impersonal code

The ideal state to be reached in this process is called an impersonal code. I am sure that many of you, having opened a working draft and a random component, can offhand say which of your colleagues wrote it. Everyone often has a style. Someone likes noodles from if, someone about and without lambda fuss, someone likes to shorten variables in such a way as to save one character. You won't be able to do this in an anonymous code. In an ideal impersonal code, it is impossible to determine the author. And this is the case when you came to the final point of your codestyle.

Book level readability

Recall the 2 main problems of programming? Cache invalidation and variable naming. Let's bypass the dark past of caching processes and go straight to our pain. Naming of variables, classes, objects, files, methods, constants and so on. This problem has 2 extremes. Names are too short and too long. Common sense suggests that logic is somewhere near, near the middle. Then super-efficient programmers will knock on our door and tell us that they don’t care. But why should we theorize about it? Tell me what this code does?

And this one?

The second code is read directly and easily. You don't need to have a deep understanding of business logic to understand the functional load with this naming. In this example, we just grab the entire repository, then use builder to create the collection, then apply the filter. You don't even need to delve into the code to understand what's going on. Like reading a book by title. But naming isn't everything.

Design patterns

You are asked about design patterns in almost every job interview. Their public goal is a repeatable architectural solution. Their side effect is predictability and consistency. The moment you move to an architecture based on design patterns, you form a fairly predictable system. Those. Based on the name, you can easily understand the purpose of a class or object. What does the Repository pattern do? This is a storage view with data retrieval methods. What does the Builder pattern do? Assembles a complex object or structure. And so on all fronts.

There is such a pattern as Command. what can we do with him? Of course, only execute! You do not need to study what is inside it. It is clear that it can be done. Design patterns help you understand how your project works. If you wrote everything well, then you will not ask yourself: “What do I have in these directories?”. By name, you can easily determine what and where is located.

Let's just say. All solutions based on design patterns were formed, basically bearing the pain of the developer on a particular problem. This pain has already been experienced by someone, framed and received its solution in the form of one of the existing architectural models. Moreover, all this was formed on top of the notorious SOLID.

SOLID

SOLID is an acronym for the Five Principles of Object Oriented Programming. Note: 5 principles. Object-oriented. Programming. This is not practice. This is not a recommendation. This is not the desire of some old programmer to teach the youth. And in many places you can hear that SOLID is principles. But if you look at the SOLID manifesto, which described 6 signs of a bad design, you will find that SOLID is not just principles. These are the conditions under which your project will have flexibility, extensibility, and predictable behavior for the developer. And failure to comply with any of the principles is a violation of the terms of the contract with the code base in which you lose one of the qualities. Whether it's readability, flexibility, or dependency on abstractions, whatever you lose, this is the beginning of the design or component you'll be rewriting. From scratch. Because it is much more difficult to do it right in the resulting implementation than to quickly introduce the next incorrect inclusions.

How many project rewrites have you seen? How many of these have you participated in? Not one or two. In every company, you will find a component or an entire system that was designed without a development culture. Without a good code style, without design patterns, without taking into account the conditions of SOLID. Development departments are rewriting code every day. Double work. Often rewriting in the same hard-to-read components. And the only plus of such rewriting is the acquaintance of a specialist with business logic. Those. you rewrote the code, you think you understand it, but you understand it not because it has become simpler, lighter, better designed. In most cases, it is now understood simply because they themselves rewrote it.

It is worth taking away from this that code style is a form of social contract within your community in the company. You agree on how to write the code, taking into account the specifics of the business, the code itself, the architecture, and plans to change the code base. This agreement means that everyone respects it. Teamwork is not so much about working together as working for the benefit of the team. This is not coworking, this is a common goal that everyone is moving towards. As a result, one of the goals is the cleanliness of the code as a tool for further development.

Which code style to choose? Doesn't matter! This is not a discussion of taste. We are training a neural network, which means that it does not matter what exactly will be in the training set. It is important that these are the same blocks. It doesn't matter what they look like. But it is better to take something from open-source based styles. Just based on the fact that PSR knows more people than some custom one. Not to mention the extremely common symfony2 code style, which is actually an improvement and extension of PSR. This, of course, is about PHP. They have a built-in high-quality box model that is easy to read, easy to add to, and easy to maintain.

Why all this?

You probably want to know where this will lead? I will give an example from one of the previous places of work - it turned out to be a pure experiment, given that CodeStyle issues did not bother the team before I raised this issue. When I came to the team and said that from tomorrow such a funny beast as phpcs and the codestyle protocol will start up in your PHPStorm, everyone was a little depressed. It's not my policy to innovate through repression, I tried to convey this through the demonstration of that pile of research on pattern recognition by a programmer. And still, only a couple of people found support, who, like me, suffered greatly from reading poor-quality code.

I shrugged and started writing clean, well-designed (subjectively), isolated components. I could be wrong, right? Certainly can. And then he began to distribute tasks of identical complexity to the same people in new pure components and in the old ones. Gradually, carefully collecting statistics. After 2 months, I pulled up my tablet in Google Sheets and showed it to the team. On pure code, the efficiency of programmers turned out to be 23% higher. After thinking that 7 people is not representative, I continued this practice quite quietly in a parallel project with about 20 freelance programmers. The results were somewhat worse. But yes, a small group of programmers of more than 20 people wrote pretty clean and well-designed code. And on top of their code, identical tasks were solved by others 21% faster. I wanted to move on, but it was enough to get support from the team.

Slowly but surely, we cleared the working draft of bad design, and at one point we came to a state where 90% of the code was completed according to all the development canons that we defined. What did it lead to? We have hired another Middle PHP Developer to join the team. And his onboarding took place in a month, instead of the usual 3. And then another one of the same... Complex business logic and asynchronous interaction are always difficult. But not in this case. Our onboarding has taken on the character of quickly learning business logic, and not the classification of drugs under which each piece of code is written. We have come to a state where only 1 month is enough before issuing a large and serious task, even a Junior PHP Developer. Communication in the style of "how it works" was kept to a minimum. And this one was really a success story.

So, just without violating the rules that were written long before today, we managed to increase team performance by almost 25% out of the blue, and drop the onboarding timing by ⅔. At the same time, the appearance of a “dirty code” inside a clean one is completely excluded, because no one will allow you to introduce something incomprehensible into a debugged and working system. And if the quality of the code is initially low, no one will notice the appearance of new worthless fragments. In addition, today there are enough tools that allow you to monitor the quality and purity of the code automatically, for example, such a phpstorm plugin as Sonar Light.

In many companies, low-quality code is the reason why you need to keep a huge staff of Senior developers, whose main value lies in the fact that they know the project and can figure out any mess. Think about it, the resources of highly skilled people are used to deal with the consequences of a lack of development culture, and not to implement technically complex systems.

Learn more

• 
  What are the method of teaching reading
• 
  Words rhyming with first
• 
  Cartoon short stories
• 
  English fairy tale
• 
  How to teach the child
• 
  Alphabets song lyrics
• 
  Song about colours for preschool
• 
  Alphabet letter lowercase
• 
  Word games for a group
• 
  What reading level should my 2nd grader be at
• 
  How to teach maths for preschoolers