Go learning notes (83) - code specification and common development skills

1. Specification guidelines

1.1 Package name

package The naming of should follow the following principles ：

• It's just small letters . Does not contain characters such as uppercase letters and underscores ;
• Short and contain some contextual information . for example time、list、http etc. ;
• It should not be a common name with vague meaning , Or it has the same name as the standard library . For example, you can't use util perhaps strings;
• The package name can be used as the path base name, If the package name string is too long, try to use the directory to split . For example should use encoding/base64 instead of encoding_base64 perhaps encodingbase64;
• The package name is consistent with the directory , Try to make sense , It is short and concise to represent the main functions of the package , Does not conflict with the standard library , Prevent renaming when importing packages , Full lowercase , Don't underline , Package names are not plural , for example net/url, instead of net/urls;

The following rules shall be satisfied as far as possible in order ：

• Do not use common variable names as package names . For example, using bufio instead of buf;
• Use the singular instead of the plural . For example, using encoding instead of encodings;
• Use abbreviations carefully . For example, using fmt Better than... Without breaking the context format Shorter , And some names that need to use multiple words to express the context can use abbreviations , For example, using strconv instead of stringconversion.

1.2 Variable naming

The naming of variables should follow the following principles ：

• Use... For exportable variables MixedCaps, For variables used internally, use mixedCaps;

• Acronyms are capitalized , But when it is at the beginning of a variable and does not need to be exported , Use all lowercase . For example, using ServeHTTP instead of ServeHttp, And the use of XMLHTTPRequest perhaps xmlHTTPRequest;

• Brevity is better than verbosity . For example, in a cycle , Use i Instead of sliceIndex;

• The farther a variable is from where it is used , The more context information you need to carry . For example, a global variable needs more context information in its name , So that its meaning can be easily recognized in different places ;

• The error variable name is usually in Err perhaps err start , The hump nomenclature is used later ;

• It's like a structure , Variable names generally follow the hump method , The initial letter is capitalized or lowercase according to the access control principle , But when it comes to special nouns , The following rules need to be followed ：

  • If the variable is private , The first word is a special noun , Use lowercase , Such as apiClient
  • In other cases, the original form of the noun should be used , Such as APIClient、repoID、UserID
  • The wrong sample ：UrlArray, Should be written as urlArray perhaps URLArray

• If the variable type is bool type , The name should be Has、Is、Can or Allow start

var isExist bool
var hasConflict bool
var canManage bool
var allowGitHook bool

1.2 Variable initialization

So we prefer the following form ：

var (
  a = 13
  b = int32(17)
  f = float32(3.14)
)

Instead of this seemingly inconsistent form of declaration ：

var (
  a = 13
  b int32 = 17
  f float32 = 3.14
)

1.3 Constant naming

Constants named constants are composed of all uppercase letters , And use the underline participle

const APP_VER = "1.0"

1.3 Function name

The naming of functions should follow the following principles ：

• For exportable functions, use MixedCaps, For functions used internally, use mixedCaps;
• The function name does not carry the context information of the package name . For example, using http.Server instead of http.HTTPServer, Because package names and function names always appear in pairs .
• Keep the function name as short as possible ：
  • When called foo The return type of a function in the package Foo when , Type information can often be omitted without ambiguity . For example, using time.Now() as well as time.Parse(), Both return time.Time type ;
  • When called foo The return type of a function in the package T when （T Not at all Foo）, You can add type information to the function name . For example, using time.ParseDuration() The return is time.Duration type ;
  • When called foo The return type of a function in the package Foo, And Foo Is the entrance to all its methods , have access to New() To name without ambiguity . For example, using list.New() The return is *list.List type .

1.4 Structure

• struct Declaration and initialization formats are multiline ： The definition is as follows ：

type User struct{
    
    Username  string
    Email     string
}

The initialization is as follows ：

u := User{
    
    Username: "wohu",
    Email:    "[email protected]",
}

1.5 Receiver name

The naming of receivers should follow the following principles ：

• Do not use common names in object-oriented programming . For example, don't use self、this、me etc. ;
• In general use 1 To 2 An abbreviation of four letters stands for its original type . For example, the type is Client, have access to c、cl etc. ;
• Use a uniform abbreviation in each method of this type . For example, in one of the methods c On behalf of Client, In other methods, it is also necessary to use c Instead of using things like cl The name of ;

recieved Whether the value type or the pointer type is to be used is mainly based on the following principles ：

func(w Win) Tally(playerPlayer)int    //w There will be no change  
func(w *Win) Tally(playerPlayer)int    //w It changes the data 

1.6 The interface name

The commands of the interface should follow the following principles ：

• For a with only one method interface, It is usually named method name plus er. for example Reader and Writer;
• interface Don't use some idiomatic names , Unless this method has the same effect . for example Read、Write、Flush、String、ServeHTTP;

1.7 Parameter passing

• For a small amount of data , Don't pass pointers
• For a lot of data struct Consider using pointers
• The incoming parameter is map,slice,chan,interface,string Don't pass pointers

1.8 The source file name

If you want to use more than one word in the name of the source file , We usually connect multiple words directly as the source file name , Instead of using other separators , Like underline .

in other words , We usually use helloworld.go As a file name instead of hello_world.go . This is because underscores are separators , stay Go Source file naming has a special role .

1.9 Other

1. Every base library must have an actual runnable example , The interfaces of the basic library should have unit test cases
2. Not in for Use in circulation defer,defer Only when the function exits
3. panic Capture only to goroutine At the top , Each self initiated goroutine, Must be captured at the entrance panic, And print out the detailed stack information
4. Go Built in type slice、map、chan All references , Before initial use , Must first use make Assign objects , Otherwise, there will be a null pointer exception
5. Use map Need to pay attention to ：map First use , Must use make initialization ;map Is quoted , Don't worry about assigning memory copies ; During concurrent operations , It needs to be locked ;range When traversing, the order is uncertain , Not to be relied upon ; Out of commission slice、map and func As key
6. import In the case of multiple lines ,goimports It will automatically format for you , But let's standardize here import Some of the norms of , If you introduce a in a file package, The following format is recommended ：

import (
    "fmt"
)

If your package introduces three types of packages , Standard library package , Program internals , Third party package , It is recommended that you organize your package in the following ways ：

import (
    "encoding/json"
    "strings"

    "myproject/models"
    "myproject/controller"
    "myproject/utils"

    "github.com/astaxie/beego"
    "github.com/go-sql-driver/mysql"
)   

Sequential introduction of packages , Different types are separated by spaces , The first is the standard library , The second is the project package , The third is the third-party package .

1. Print or call long sentences , Use parameters to format lines We're calling fmt.Sprint perhaps log.Sprint And so on , Sometimes I come across very long sentences , We need to split multiple lines at the parameter call ：

Here's the wrong way ：

log.Printf(“A long format string: %s %d %d %s”, myStringParameter, len(a),
    expected.Size, defrobnicate(“Anotherlongstringparameter”,
        expected.Growth.Nanoseconds() /1e6))

It should be in the following way ：

log.Printf( 
    “A long format string: %s %d %d %s”, 
    myStringParameter,
    len(a),
    expected.Size,
    defrobnicate(
        “Anotherlongstringparameter”,
        expected.Growth.Nanoseconds()/1e6, 
    ),
）   

2. Notice the call to the closure Call a function or... In a loop goroutine Method , Be sure to call with the variables shown , Don't call loop arguments in closure functions

fori:=0;i<limit;i++{
    
    go func(){
     DoSomething(i) }() // Wrong way 
    go func(i int){
     DoSomething(i) }(i)// The right way 
}

2. Development skills

• package The name of is the same as the directory name ,main With the exception of
• string Represents an immutable string variable , Yes string The modification of is a heavy operation , Basically, you need to reapply for memory , If there is no special need , Use more when you need to modify []byte
• Use as much as possible strings Library operation string, This can improve performance
• append Be careful to automatically allocate memory ,append The returned address may be the newly assigned address
• If you want to modify it directly map Of value value , be value It can only be a pointer , Otherwise, the original value will be overwritten
• map Locking is required in concurrency
• The compilation process cannot check interface{} Transformation , Only runtime checks , Be careful to cause panic
• Use defer, Ensure that resources are released when exiting the function
• Use as few global variables as possible , Pass through parameters , Make every function be “ No state ” Of , This reduces coupling , It also facilitates division of labor and unit testing
• If there are many parameters , Define relevant parameters as structure transfer

1. The code must be formatted after writing , Make sure your code is elegant gofmt -w main.go,
   gofmt yes Go Its own formatting tool , Used to organize the code format 、 Space at the end, etc . Reference resources https://pkg.go.dev/cmd/gofmt

2. Perform code static analysis before compiling ：go vet pathxxx/go vet yes Go Built-in tools , Used to check whether the program is correct . Reference resources https://pkg.go.dev/cmd/vet
   
   
   

3. Race detection ：go build –race ( Add... When the test environment is compiled -race Options , The production environment must be removed , because race The limit is at most goroutine The number of 8192 individual )

4. The length of each line is agreed ： A line should not be too long , Please use line feed to show more than , Try to keep the format elegant ; Individual files should not be too large , Better not to exceed 500 That's ok

5. Multiple return values can return up to three , For more than three, please use struct

6. Disable... In logical processing panic, Unless you know what you're doing

7. The principle of error handling is not to discard any returned err Call to , Don't use _ discarded , All must be dealt with . Error received , Or go back to err, Or if it doesn't work, just panic, Or use log recorded . Don't write like this :

if err != nil {
    

    // error handling

} else {
    

    // normal code

}

It should be :

if err != nil {
    

    // error handling

    return // or continue, etc.
}

// normal code

3. The robustness of functions

The robust design of functions includes many aspects , The first is the most basic “ Three don't ” principle

Principle one ： Do not trust any external input parameters .
The user of the function can be anyone , These people may not have read any manuals or documentation before using the function , They will pass unexpected arguments to the function . therefore , To ensure the robustness of the function , The function needs to check the validity of all input parameters . Once problems are found , Immediately terminate the execution of the function , Returns the default error value .

Principle two ： Don't ignore any mistakes .
In our function implementation , Functions or methods provided by standard libraries or third-party packages will also be called . For these calls , We cannot assume that it will succeed , We must explicitly check the error values returned by these calls . Once an error is found , Stop function execution in time , Prevent errors from continuing to propagate .

Principle three ： Don't assume that exceptions won't happen .
here , We first need to determine a cognition ： Exceptions are not errors . Errors are predictable , It happens often , We have corresponding public error codes and error handling plans , But anomalies are rare 、 Unexpected . An anomaly in the usual sense , Refers to a hardware exception 、 Operating system exception 、 Language runtime exception , There is more likely to be a potential in the code bug The resulting anomaly , For example, the code appears with 0 As denominator , Or the array is accessed beyond the bounds . Although the abnormal occurrence is “ Minority events ”, But we can't assume that exceptions don't happen . therefore , When designing functions , According to the role and usage scenario of the function , Consider whether to set the exception capture and recovery link in the function .

​
Best practices ：
https://github.com/cristaloleg/go-advice/blob/master/README_ZH.md

https://github.com/cristaloleg/go-advice

​