[Translate] effective go formatting commentary

This is a creation in Article, where the information may have evolved or changed.

Formatting (code style)

Formatting issues is the most contentious but the least consequential. People can adapt to different formatting styles but it's better if they don ' t has to, and less time are devoted to the top IC If everyone adheres to the same style. The problem is what to approach this Utopia without a long prescriptive style guide.

About code style The discussion of this menstrual paste lasts long if we all use the same style these unnecessary arguments have long been able to get rid of the name of the menstrual paste and also save everyone's time but how to achieve this ideal state?

With Go We take a unusual approach and let the machine take care of the most formatting issues. The GOFMT program (also available as Go FMT, which operates on the package level rather than source file level) reads a go Program and emits the source with a standard style of indentation and vertical alignment, retaining and if necessary reform Atting comments. If you want the know to handle some new layout situation, run gofmt; If the answer doesn ' t seem right, rearrange your program (or file a bugs about Gofmt), Don's work around it.

Go does not go the normal way to let the machine solve most of the formatting problems gofmt This tool can standardize indent vertical alignment if necessary, it will also rearrange the format of the annotation

As an example, there's no need to spend time lining up the comments in the fields of a structure. Gofmt'll do. Given the Declaration

Here's an example where you don't have to waste your time on structural field alignment.

Type T struct {    name string//Name of the object    value int//its value}

Gofmt'll line up the columns:

GOFMT can help you solve this problem. Column alignment:

Type T struct {    name    string//Name of the object    value   int    //Its value}

All Go code in the packages have been formatted with GOFMT.

All go standard packs use GOFMT to organize code styles

Some formatting details remain. Very briefly,

Some of the other style details are not discussed here first simply

Indentation We use tabs for indentation and gofmt emits them by default. Use spaces only if you must. Line Lengthgo have no line length limit. Don ' t worry about overflowing a punched card. If a line feels too long, wrap it and indent with an extra tab. Parenthesesgo needs fewer parentheses:control structures (if, for, switch) does not has parentheses in their syntax. Also, the operator precedence hierarchy is shorter and clearer, so

use tab to indent gofmt default tab if not necessary, do not use a space to indent (this does not quite agree with the vim to write Python is used to indent the use of space to indentation of the sample script is all the tab that program can not be changed) go to the length of the line is not displayed You don't need one, but a line of code is more than 70 characters now, a single line on a large screen can hold one hundred or two hundred characters, but it's better to break the line. You can add an extra tab go. It is very rare to use parentheses if switch conditions to determine that the precedence of the parentheses operator is more concise:

X<<8 + y<<16

means what the spacing implies.

The code shown above can be interpreted according to the meaning of the space split.

Commentary notes

Go provides C-style/* */block comments and C++-style//line comments. Line comments is the norm; Block comments appear mostly as package comments and is also useful to disable large swaths of code.

Go can use C or C + + stylish comments/**///

The Program-and Web Server-godoc processes Go source files to extract documentation on the contents of the package. Comments that appear before top-level declarations, with no intervening newlines, is extracted along with the declaration To serve as explanatory text for the item. The nature and style of these comments determines the quality of the documentation Godoc produces.

The comments in Go and the doc string in Python are a bit like those comments that are close to the function package definition (no blank lines are used in the middle)Godoc can pull them out as documents

Every package should has a package comment, a block comment preceding the package clause. For multi-file packages, the "package comment" only "needs to being present in one file, and" any one "would do. The package comment should introduce, the package, and provide information relevant to the package as a whole. It would appear first on Thegodoc page and should set up the detailed documentation that follows.

Add package comments for each package if a package has many files then the master needs to add a package comment to the file.

/* Package    RegExp implements a simple library for    regular expressions.    The syntax of the regular expressions accepted is: regexp    :        concatenation {' | ' concatenation}    concatenation:        {closure}    closure: term        [' * ' | '+' | '?' ]    Term:        ' ^ ' '        $ '        . '        Character        ' [' [' ^ '] character-ranges '        (' regexp ') ' */package regexp

If The package is simple, the package comment can brief.

The length of the note is subject to availability

Package path implements utility routines for//manipulating slash-separated filename paths.

Comments do not need extra formatting such as banners of stars.  The generated output may is not even is presented in a fixed-width font, so don ' t depend on spacing for alignment-godoc, like GOFMT, takes care of. The comments is uninterpreted plain text, so HTML and other annotations such as _this_ would reproduce verbatim a nd should not being used. Depending on the context, Godoc might not even reformat comments, so make sure they look good straight up:use correct SPE lling, punctuation, and sentence structure, fold long lines, and so on.

Note No additional formatting markup is required to generate a document that may not be a fixed-width font, so don't just rely on spaces to align Godoc and gofmt. Comments are simple words do not use HTML or other tags

Inside a package, no comment immediately preceding a top-level declaration serves as a doc comment for that decl Aration. Every exported (capitalized) name in a program should has a doc comment.

Annotations such as the declaration function definition are treated as declaration documents. All the names that can be exported require a document comment

Doc comments work best as complete sentences, which allow a wide variety of automated presentations. The first sentence should is a one-sentence summary that starts with the name being declared.

Document comments It's best to have a complete sentence so that you can better automate the presentation. The first sentence should be a brief summary with the name of the description the comment is similar to the way Git recommends writing comments

Compile parses a regular expression and returns, if successful, a regexp//object that can is used to match against Tex T.func Compile (str string) (RegExp *regexp, err error) {

Go ' s declaration syntax allows grouping of declarations. A single doc comment can introduce a group of related constants or variables. Since the whole declaration is presented, such a comment can often be perfunctory.

Go's declaration syntax allows one VAR to declare multiple variables a document comment can be taken with this (code below) as the entire statement is written to the beginning of the document in the sentence that is to play a role

Error codes returned by failures to parse an Expression.var (    errinternal      = errors. New ("regexp:internal error")    Errunmatchedlpar = errors. New ("regexp:unmatched" (') ")    Errunmatchedrpar = errors. New ("regexp:unmatched ') ')    ...)

Even for private names, grouping can also indicate relationships between items, such as the fact, a set of variables I s protected by a mutex.

Even a private name that puts a couple of variables together can imply some kind of connection between them. The following variables are protected by mutexes.

var (    countlock   sync. Mutex    inputcount  uint32    outputcount uint32    errorcount  uint32)