This document gives tips for writing clear, idiomatic Go code
-and points out common mistakes
+and points out common mistakes.
It augments the <a href="go_spec.html">language specification</a>
and the <a href="go_tutorial.html">tutorial</a>, both of which you
<h3 id="read">Read good code</h3>
-The first step
towards learning to write good code is to read good code.
+The first step learning to write good code is to read good code.
The <a href="/src/pkg/">Go package sources</a>
are intended to serve not
only as the core library but also as examples of how to
<h3 id="be-consistent">Be consistent</h3>
-Consistency makes programs easy to read.
-If a program says the same thing twice,
-it should say it the same way both times.
+Programmers often want their style to be distinctive,
+writing loops backwards or using custom spacing and
+naming conventions. Such idiosyncracies come at a
+price, however: by making the code look different,
+they make it harder to understand.
+Consistency trumps personal
+expression in programming.
+If a program does the same thing twice,
+it should do it the same way both times.
Conversely, if two different sections of a
program look different, the reader will
expect them to do different things.
in most languages (including Go)
is to count up unless to do so would be incorrect.
A loop that counts down implicitly says “something
special is happening here.”
A reader who finds a program in which some
loops count up and the rest count down
will spend time trying to understand why.
-Don't run loops backwards unless it's necessary.
Loop direction is just one
-programming decision which a programmer
-may be tempted to be distinctive:
-tabs or spaces, choice of variable names,
-choice of method names, whether a type
-has a constructor, what tests look like, and on and on.
-As in the loop example, inconsistency
-sows confusion, and wastes time.
+programming decision that must be made
+consistently; others include
+formatting, naming variables and methods,
+has a constructor, what tests look like, and so on.
Why is this variable called <code>n</code> here and <code>cnt</code> there?
Why is the <code>Log</code> constructor <code>CreateLog</code> when
the <code>List</code> constructor is <code>NewList</code>?
Why is this data structure initialized using
a structure literal when that one
is initialized using individual assignments?
These questions distract from the important one:
Moreover, internal consistency is important not only within a single file,
but also within the the surrounding source files.
-Being consistent about little things
-lets readers concentrate on big ones.
-This document describes how to use Go effectively and idiomatically
-so that a programmer seeing your code for
-the first time can focus on what it does
-and not why it is inconsistent with typical Go practices.
-Consistency trumps every item listed below.
When editing code, read the surrounding context
and try to mimic it as much as possible, even if it
disagrees with the rules here.
It should not be possible to tell which lines
you wrote or edited based on style alone.
+Consistency about little things
+lets readers concentrate on big ones.
Formatting issues are the most contentious
but the least consequential.
People adapt to different formatting styles,
-even if at first the styles “look weird,”
but they shouldn't be asked to.
should use the same formatting; as in English,
consistent punctuation and spacing make the
Most of the local formatting style can be
-picked up by reading existing Go programs
+picked up by reading existing Go programs,
but to make them explicit here are some common points.
<h3 id="tabs">Use tabs</h3>
-The local style is to use tabs, not spaces, for indentation.
+Use tabs, not spaces, for indentation.
+<h3 id="columns">Don't worry about columnation</h3>
+Let tools such as <code>gofmt</code> take care of lining things up.
<h3 id="white-space">Trim trailing white space</h3>
There should be no trailing white space at the end of lines.
-<h3 id="line-wrapping">Don't wrap lines
+<h3 id="line-wrapping">Don't wrap lines</h3>
Go has no 80-character limit. Don't bother with fancy line
wrapping just because a line is wider than a punched card.
you must wrap a line, indent with an extra tab.
+If , indent with an extra tab.
<h3 id="parens">Omit parentheses in control structures</h3>
The complete English sentence form admits
+ complete English sentence admits
a wider variety of automated presentations.
<h3 id="else">Omit needless else bodies</h3>
-If an <code>if</code> body doesn't flow off the end of the
-body—that is, the body ends in <code>break</code>, <code>continue</code>,
+When an <code>if</code> statement doesn't flow into the next statement—that is,
+the body ends in <code>break</code>, <code>continue</code>,
<code>goto</code>, or <code>return</code>—omit the <code>else</code>.
+<h3 id="error-returns">Return <code>os.Error</code>, not <code>bool</code></h3>
+Especially in libraries, functions tend to have multiple error modes.
+Instead of returning a boolean to signal success,
+return an <code>os.Error</code> that describes the failure.
+Even if there is only one failure mode now,
+there may be more later.
<h3 id="handle-errors-first">Handle errors first</h3>
f, err := os.Open(name, os.O_RDONLY, 0);
-<h3 id="error-returns">Return <code>os.Error</code>, not <code>bool</code></h3>
-Few functions have just one failure mode.
-Instead of returning a boolean to signal success,
-return an <code>os.Error</code> that describes the failure.
-Even if there is only one failure mode now,
-there may be more later.
<h3 id="error-context">Return structured errors</h3>
Implementations of <code>os.Error</code>s should