How to write code more standardized? Let's see the analysis of netizens

These days, I was scolded by my boss for writing programs in a weird way. He had never seen such a way of writing. I am actually a person who pays attention to these things. Unfortunately, my personal programming style comes from various codes and books I have come into contact with, so there is no systematic standard.
In China, the most powerful company in our industry should be Huawei, and they also have a set of programming standards that have been circulated.
There are all kinds of shameless downloads on the Internet with messy names, and you will find that most of the downloaded ones are the same.
Of course, different languages, such as Java and Python, are of course different, but those that say C C++ are the same, basically the 59-page general rules.

These days, the work at hand is welding boards, and there are two people working together, so I quietly read this document in some free time. Because of the previous experience, I am not in a hurry to finish it all at once this time. I decided to stop when I get tired of it. I read about a dozen pages a day, and then consolidate it the next day.

I finished it by Friday, so I need to take notes.

First, let's take a look at the table of contents, and then start from here to summarize the full text

There are 12 sections in total
1 Formatting, which is what we call code appearance
2 Comments
3 Identifier commands It doesn't write variables and functions. I think it is very cultural
4 Readability
5 Variable structure
6 Function process
7 Testability
8 Program efficiency
9 Quality assurance
10 Code editing, compilation and review
11 Code testing and maintenance
12 Macros

From the content point of view, many of these contents are things that you just need to listen and follow. You have to say something very technical. There is no reason. The only reason is that you have to be empathetic, consider others, and consider that you will have to maintain it in the future
For example, the first chapter is, and the other is that most people, as long as they are not too lazy or rebellious, basically write codes that meet certain specifications
It's just that Huawei's specifications are more detailed and systematic.

So, as usual, we have to do it again, but for simplicity, I will only explain it from my perspective, because the specifications he mentioned are relatively general and common, so most of them don't need to be said much.

1. The

indentation problem. The most tangled part of this problem is not whether to indent with 4 spaces or 8 spaces.
The biggest problem is whether to indent with tabs or spaces.

Let's analyze the advantages and disadvantages of both sides:
1. Tab is comfortable. This is the most direct and of course comfortable. Tab is even more comfortable for those who are used to the command line.
2. Tab can be aligned. Yes, when tab is indented, it will automatically align. Even if you delete a few letters when modifying the code, it will automatically keep the position;
3. Tab does not need to be counted. It's great. Mom no longer worries that I will count wrong with my fingers.

However, the behavior of tab is very dependent on the editor, which is the worst. You may often see all kinds of messy code on the website. Believe me, their authors are definitely not deliberately disgusting you and themselves. It's just because of the evil tab. Because different editors and even web pages have different interpretations of tabs, so spaces can avoid this problem.
However, basically speaking, the advantages of the above 123tab are its disadvantages.

What's even more frustrating is that~~ you don't hesitate to choose spaces, we can count well, but unfortunately your boss (or project team) likes tabs, so what else can we say? Tabs

- we will encounter various tangled situations like this, believe me, my choice is
- boss, I listen to you!

2. Statements and blank lines
Generally speaking, we only write one statement in a line; generally speaking, we add blank lines between several slightly unrelated statements to show the closeness of the logical relationship...
Unfortunately, I always meet people who are unwilling to do this, and they may find more reasons than you~~
Actually, here I think this way, first, we programmers are not paid by the number of lines of code, so no matter how honest you are, you don't have to be so honest;
second, a blank line is like an enter, will it lose an arm or a leg! ... How many lines do you want to read at a time? You think you... Forget it, be polite, be polite.

Of course, what I said doesn't have much weight, but since Huawei has said so, let's just follow it~~

3. Line breaks for long statements
In fact, all long statements should be line broken. We should know that there is a very beautiful programming style under Unix, that is, the maximum length of each line does not exceed 80 characters.
Therefore, I really like the gray and white border in iar.
As for how to break, it is of course based on the priority and logical relationship between the parts of the statement. As long as you don't write it like this, I think others will not kill you

if (Architecure || da
ta)
.......
You know, it actually wants to write if (Architecure || data)
Of course, this writing is actually not compilable, I just deliberately disgusted it here~~

2. Comments
Comments are also a very exciting place, so we need to stay calm. . . . . . . .

In this section, the following places are relatively new to me:
1. Header comments of source files and header files.
Most of them are the same, and the only essential difference is the name of the description, which is the description part.
This part of the header file should describe its interface and the relationship with external files... In short, it should be a description for external references and calling related functions of this module;
while the source file, it describes more about the relationship between the various parts of this module, how to implement it, and internal dependencies.
In Huawei's specifications, this part of the source file also involves a part that mentions external dependencies. I am a little confused and don't know why, but I think that if there is such a description of external dependencies, it must be related to internal implementation before it is necessary!
——Because I suddenly realized that the fundamental reason for the difference between the two descriptions is that they face different things. The source file is the implementation, and the header file is the interface for external calls. Naturally, one description tends to be internal, and the other tends to be external.

2. Use as few abbreviations as possible in comments - In fact, I don't like abbreviations anywhere, because we are not native English speakers, who is better at English? I guess the good ones have gone abroad, right?
Moreover, even in the later part of the identifier command, some abbreviations are mentioned, such as abbreviations with vowels, such as temp as tmp and flag as flg. I just want to type less a or e?
Programming language, like any other language, is a medium for communication, and the language barrier itself will cause more or less trouble in communication - not to mention English, even if we all use Chinese, there may still be communication troubles.
So, let's not care so much about turning four letters into three letters, okay?

3. I am a little confused about this.
Whether it is function comments or global variable comments, I find that they are very detailed, so detailed that there are function lists, and even function call and callee lists.
What's even more exaggerated is that for variables, it even needs to fully describe their meaning, value range, and value meaning...

To be honest, I write a lot of comments, so much so that my colleagues often laugh at me for writing essays. However, even so, I still think that such comments are too complete.

So, whether to write or not, and how to write, this is indeed a trade-off.
But there is one thing that I think is very inspiring.

It is very important to clearly describe the dependencies and hierarchical relationships between important variables or functions.
But to be honest, I think it is very weak to use text to annotate this thing. We should use diagrams, which is probably the meaning of things like UML.
But, damn, maybe in the field of OOP, there are more people using this. Anyway, in my industry, whether it is the online circle or my peers in real life, I rarely hear them mention UML.

4. Annotate branch statements
I didn't have this comment habit in the past. Because I usually use macros to describe each literal in each branch of switch-case, and then I hope to express the intention of this branch through this literal, that is, I hope to achieve self-annotation through this macro method.
However, in fact, this specification is right in this place.
The situation of a branch is often not explained by a macro state value or quantity value. Adding some necessary comments here is indeed very effective, and even replaces the design document -
yes, if possible, I hope to have 0 design documents, and all text descriptions, including design intent, are conveyed through code and comments. - Because personally, I also don't like to compare documents while reading code.

3. Identifier commands
In this section, I am convinced by most of them. Maybe I do this myself. There are only two:
1. I don't like abbreviations, including temp-tmp flag-flg. I don't like them. The reason is mentioned above. From four letters to three letters, is it interesting?
2. 3-5 mentioned that the naming style should be similar to the system style.
For example, it mentioned the unix system.
In the example, it mentioned that the unix system uses uppercase and lowercase or pure lowercase plus underscores to distinguish names, so
Add_User is not allowed, while add_user or AddUser are allowed.
I thought about this and it was quite reasonable. Looking back on what I did, it was indeed not standard enough, because I didn't particularly understand this subtle point, and I often mixed them.
I have done all three types of naming.

For more information, please click below to read the original text.