This article is translated from the official FAQ

Original address: golang.org/doc/faq#Wri…

Go language coding

How is the Go library documentation constructed?

There is a GoDoc program written in Go that extracts package documentation from source code and uses it as a web page containing links to declarations, files, and so on. The example is running at golang.org/pkg/, and in fact, GoDoc implements the full site at golang.org/.

Godoc instances can be configured to provide rich interactive static symbol analysis in the programs they display; Details are listed here.

To access documents from the command line, the Go tool has a doc subcommand that provides a text interface to the same information.

Is there a Go programming style guide?

While there is certainly some “Go style” coding, there is no official style guide.

Go is established to guide convention decisions about naming, layout, and file organization. The document Effective Go contains recommendations on these topics. More directly, the program Gofmt is a nifty printer whose purpose is to enforce layout rules. It replaces compilation, which is normally allowed and disallowed by assembly. All of the Go code in the repository and most of the code in the open source world already runs through Gofmt.

The document titled Go Code Review Comments is a collection of very short articles about the details of Go idioms that programmers often ignore. It is a handy reference for people doing code reviews for Go projects.

How do I submit a patch to the Go library?

The library source is located in the SRC directory of the repository. If you want to make major changes, discuss them on the mailing list before committing.

For more information on how to proceed, see the documentation “The Go Project.”

Why would “Go Get” use HTTPS when cloning a library?

Companies typically only allow outgoing traffic on standard TCP ports 80 (HTTP) and 443 (HTTPS) to block outgoing traffic on other ports, including TCP ports 9418 (git) and TCP ports 22 (SSH). Git enforces certificate validation by default when using HTTPS instead of HTTP, preventing man-in-the-middle, eavesdropping, and tampering attacks. Therefore, the go get command uses HTTPS for security.

Git can be configured to authenticate over HTTPS or to use SSH instead of HTTPS. To authenticate with HTTPS, you can add a line to the $HOME /.netrc file that git queries:

machine github.com login USERNAME password APIKEY
Copy the code

For GitHub accounts, the password can be a personal access token.

Git can also be configured to use SSH instead of HTTPS to match urls that match a given prefix. For example, to use SSH for all GitHub access, add these lines to ~ /.gitconfig:

[url "ssh://[email protected]/"]
	insteadOf = https://github.com/
Copy the code

How should I use “Go Get” to manage versions of packages?

The Go toolchain has a built-in system for managing the version set (called a moudle) of related packages. Moudle was introduced in Go 1.11 and has been available for production since 1.14.

To create projects using modules, run Go Mod init. This command creates a go.mod file that tracks dependency versions.

go mod init example.com/project
Copy the code

To add, upgrade, or degrade dependencies, run Go Get:

go get golang.org/x/text@v03.. 5
Copy the code

For more information about getting started, see the tutorial: Creating a Module.

For guidance on using modules to manage dependencies, see Developing modules.

Packages in modules should follow import compatibility rules, and backward compatibility should be maintained when importing:

  • If the old package and the new package have the same import path, the new package must be backward compatible with the old package.

The Go 1 compatibility guide is a good reference here: don’t delete exported names, encourage labeled compound text, and so on. If you need additional functionality, add a new name instead of changing the old name.

Moudle encodes this using semantic versioning and semantic import versioning. If you need to break compatibility, release the module as a new major version. Major 2 and later modules require a major version suffix (e.g. / v2) in their paths. This preserves the import compatibility rule that packages in different major versions of modules have different paths.