It is easy to find a lot of code specifications on the Internet. Except for the problem of copying a lot of articles in the world, most of them only give the results. The reasons are not fully explained, or they are very entangled in uppercase and lowercase. A function can write a few lines of details . It feels a bit easy to lead newcomers astray.
So Uncle Guo intends to analyze the reasons for these regulations based on his own experience, and help newcomers understand why such regulations are so, know why and why.
1. The origin of "code specification"
If you have not taken over the code of other students at work, it will definitely be an order of magnitude worse than the "big cows" who have taken over the code of resigned students and often help other students troubleshoot bugs .
If you haven’t participated in the iterative development of a system module that lasts for more than 3-5 years and requires frequent changes, it’s not easy for you to understand the importance of code refactoring to improve the quality of a module with minor modifications and bugs one after another . .
The person responsible for the iterative efficiency and quality of the software is usually the Team Leader, PM, the first responsible person. After careful consideration, they came to an important conclusion. The above pits that are difficult to handover, difficult to modify, and rampant with bugs, To a large extent, it is related to the non- standard writing of the code , so the code specification is written .
2. The function of code specification
The essence of a programmer is also a craftsman, which is similar to the role of construction specifications in most other industries. The main function is to
1. Avoid construction defects and provide construction quality.
2. It is convenient for colleagues to communicate with each other for later maintenance.
For example, Uncle Guo’s home was recently being renovated, because it was not redecorated from the rough, so the wiring of some water and electricity is not very clear, and the construction has been completed before the renovation. Theoretically, the switch and socket lines can be laid at will, as long as they are connected, they can be arranged in a row for a while, and in characters for a while. At this time, for example, if you need to hang a picture or a mirror on the wall, and you need to drill a hole in the wall to fix it, then whether the hole will penetrate the water and electric wires in the wall is very random. The installer can only judge according to the wiring specifications and experience. Generally, the wiring of the wires is horizontal and vertical on the wall, and will not be inclined or circled, and the water pipes generally go up or down. You can only pray that the hydropower master who worked before followed this specification. If he has a personality in the wiring and causes you to break the line and need to repair it again, you will definitely greet him in your heart.
3. The content of the code specification
In practice, many teams should "borrow" the content of the code specification. Uncle Guo actually suggested that after learning from it, we should also pay attention to later adjustments and supplements. The technology stack and project characteristics of each team will be different, and the focus of programming will also be different. Code review should not simply be based on specifications, but should be aimed at improving maintainability. The content found in the review but not included in the code specification should be added in time. At the same time, attention should also be paid to conveying the purpose of the specification during the review, not just for everyone to follow it mechanically.
The following are some of the more common and important ones that Uncle Guo thinks are more common and important. Let me give a brief explanation, and the rankings are in no particular order.
1. Don’t use magic numbers
readability, experience
if(deviceState == 1){
doSomeThing();
}
//对比
if(deviceState == DEVICE_STATE_ON){
doSomeThing();
}2. The method should not be too long, pay attention to layering, and hide details
Reasonable stratification, self-experience
function A(){
买菜();
备菜();
炒菜();
}
vs
function B(){
……
下楼；
打开车门；
按下点火开关；
打左转向灯；
鸣笛；
开出车位；
如果遇到隔壁老王就打个招呼；
出小区右转；
第二个十字路口左转；
进菜市场左转第一个摊位，买两斤黄瓜；
拿上黄瓜，步行回车上；
扫码交车费；
…………
}3. Variables and method names must have accurate meanings
function A(){
if(a == 1){
B();
}else{
C();
}
}
//VS
function 送礼物(){
if(用户性别 == 男){
送茅台();
}else{
送古驰();
}
}4. Invalid logic should be cleaned up in time
I'm too lazy to give an example, experience it yourself
5. The function of the method should correspond to the name, and no actions beyond the scope of the name should be performed
The gift-giving method, which does something other than what he named it, is easily misused by the caller
function 收礼不办事举报(){
送礼物();
if(不办事 并且 不是我干爹){
举报他();
}
}
//VS
function 送礼物(){
if(用户性别 == 男){
送茅台();
}else{
送古驰();
}
if(不办事){
举报他();
}
} 6. For errors in user operations, ensure that there is error feedback.
Typical situations such as no data and failure to return data are different situations, which need to be distinguished.
7. System errors should have logs
Mistakes should be written in the log, so as not to die without evidence. . -_-||
8. Time-consuming operations require the interface to perform asynchronous waiting processing
Let the user know that it is being processed now, and it is not a system failure.
9. Business list query needs to be paginated
When there are hundreds of millions of data records, taking them all out at once and putting them into memory may cause the server to crash...
10. ………………