On code specification

Time:2022-4-21

  

Code specification is easy to get a pile of Baidu on the Internet. In addition to the problem of copying articles all over the world, most of them only give the results. The reasons are not fully explained, or they are very tangled in uppercase and lowercase. A function can write a few lines of details. It feels a little easy for newcomers to go astray.

Therefore, uncle Guo plans to analyze the causes of these norms according to his own experience, so as to help newcomers deeply understand why they are so stipulated, know what they are and why they are.

  1、 Origin of “code specification”

  If you haven’t taken over the codes of other students at work, it will be better than taking over the codes of former students. You often help other students check the “big cows” of bugsCode maintainabilityOur understanding should be one order of magnitude worse.

If you haven’t participated in the iterative development of a system module that lasts for more than 3-5 years and changes frequently, it’s not easy for you to understand,code refactoringFor a minor modification, the importance of improving the quality of the module with one bug after another.

People who are responsible for the iterative efficiency and quality of software are usually team leaders and PMS. After careful consideration, they come to an important conclusion that the above pits, which are difficult to handover, difficult to modify and rampant bugs, are largely different from the codestandardRelevant, so it is preparedCode specification.

2、 Code specification function

  The essence of a programmer is also a craftsman, which is similar to the role of construction specifications in most other industries

1. Avoid construction defects and provide construction quality.

2. Facilitate peer communication for later maintenance.

For example, uncle Guo’s house is being renovated recently, because it is not renovated from the blank, so the routing of some water and electricity is not very clear, and the construction has been completed before the decoration. In theory, the switch socket line can be laid at will. As long as China Unicom is connected, it can be arranged in a word for a while and in a word for a while. At this time, for example, you need to hang a picture or mirror on the wall, and you need to punch a hole in the wall for fixation. Whether this hole will penetrate the water wire in the wall is very easy. The installer can only judge according to the wiring specifications and experience. The general wiring of wires is horizontal and vertical on the wall, and will not come obliquely or turn in circles. The water pipes generally go up or down. You can only pray that the water and electricity master in the previous construction follows this specification. If his wiring is very personalized, resulting in you breaking the line and having to repair it again, you will greet him in your heart.

  3、 Content of code specification

In practice, many contents of code specifications should be “borrowed” by the team. Uncle Guo actually suggested that after learning from it, we should also pay attention to the later adjustment and supplement. The technical stack and project characteristics of each team will be different, and their programming concerns will also be different. Code review should not simply be based on the specification, but should be aimed at improving maintainability. The contents found in the review but not included in the code specification shall be supplemented in time. At the same time, during the review, attention should be paid to the purpose of communicating the specification, not just to let everyone mechanically comply with it.

Here are some common and important things that uncle Guo thinks are more common. Give a simple explanation and rank in no order.

1. Don’t use magic numbers

  Readability, own experience

if(deviceState == 1){
     doSomeThing();      
}
//Contrast
if(deviceState == DEVICE_STATE_ON){
     doSomeThing();      
}

2. The method should not be too long. Pay attention to layering and hide details

  Reasonable stratification and self experience 

function A(){
      Buy vegetables ();
      Prepare vegetables ();
      Fried vegetables ();
}

vs

function B(){
      ... go downstairs;
      Open the door;
      Press the ignition switch;   
      Turn on the left turn signal; Whistle;
      Leave the parking space; If you meet Lao Wang next door, say hello;
    Turn right when leaving the community; Turn left at the second intersection; 
      Turn left into the first stall in the vegetable market and buy two kilograms of cucumber;
    Take the cucumber and walk back to the car; Scan the code and pay the fare; 
    …………
}

 3. The naming of variables and methods should have accurate meaning

function A(){
    if(a == 1){
        B();
    }else{
        C();  
    }  
}    
//VS
Function gift (){
    If (user gender = = male){
         Send to Maotai ();
     }else{
         Send Gucci ();
     }          
}

4. Invalid logic shall be cleared in time

  I’m too lazy to give examples and experience it myself  

5. The function of the method shall correspond to the naming, and no action beyond the naming scope shall be taken

  The gift giving method does something other than his name, which is easy to be misused by the caller

Function receiving gifts without handling affairs report (){
    Give gifts ();
    If (no business and not my godfather){
         Report him ();
    }
}
//VS  
Function gift (){
    If (user gender = = male){
         Send to Maotai ();
     }else{
         Send Gucci ();
     } 
     
     If (do nothing){
       Report him ();  
    }         
}

6. Make sure there is error feedback for user’s operation errors.

  Typically, if there is no data and an error occurs, the failure to return data is different, which should be distinguished.

 

 7. System errors should be logged

  Errors should be recorded in the log, so as not to be irrefutable-_-||  

8. Time consuming operation requires asynchronous waiting processing on the interface

Let the user know that it is being handled now, not a system failure.

  

 

 9. Pagination is required for business list query

  When hundreds of millions of data records are taken out at one time and put into memory, the server may be down

      10. ………………