2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<h2 id="introduction">Introduction</h2>
|
|
|
|
|
2009-08-03 15:07:19 -06:00
|
|
|
<p>
|
2009-08-19 14:24:24 -06:00
|
|
|
Go is a new language. Although it's in the C family
|
2009-08-03 15:07:19 -06:00
|
|
|
it has some unusual properties that make effective Go programs
|
2009-08-19 14:24:24 -06:00
|
|
|
different in character from programs in existing languages.
|
|
|
|
A straightforward translation of a C++ or Java program into Go
|
2009-08-19 17:39:25 -06:00
|
|
|
is unlikely to produce a satisfactory result—Java programs
|
2009-08-19 14:24:24 -06:00
|
|
|
are written in Java, not Go.
|
|
|
|
On the other hand, thinking about the problem from a Go
|
|
|
|
perspective could produce a successful but quite different
|
|
|
|
program.
|
|
|
|
In other words,
|
|
|
|
to write Go well, it's important to understand its properties
|
2009-08-03 15:07:19 -06:00
|
|
|
and idioms.
|
2009-08-19 14:24:24 -06:00
|
|
|
It's also important to know the established conventions for
|
|
|
|
programming in Go, such as naming, formatting, program
|
|
|
|
construction, and so on, so that programs you write
|
|
|
|
will be easy for other Go programmers to understand.
|
2009-08-03 15:07:19 -06:00
|
|
|
</p>
|
|
|
|
|
2009-06-25 10:38:35 -06:00
|
|
|
<p>
|
2009-08-19 14:24:24 -06:00
|
|
|
This document gives tips for writing clear, idiomatic Go code.
|
2009-06-25 10:38:35 -06:00
|
|
|
It augments the <a href="go_spec.html">language specification</a>
|
|
|
|
and the <a href="go_tutorial.html">tutorial</a>, both of which you
|
2009-07-06 16:15:56 -06:00
|
|
|
should read first.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-19 14:24:24 -06:00
|
|
|
<h3 id="read">Examples</h3>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<p>
|
|
|
|
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
|
2009-08-19 14:24:24 -06:00
|
|
|
use the language.
|
|
|
|
If you have a question about how to approach a problem or how something
|
|
|
|
might be implemented they can provide answers, ideas and
|
|
|
|
background.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="formatting">Formatting</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Formatting issues are the most contentious
|
|
|
|
but the least consequential.
|
2009-08-19 14:24:24 -06:00
|
|
|
People can adapt to different formatting styles
|
|
|
|
but it's better if they don't have to, and
|
|
|
|
less time is devoted to the topic
|
|
|
|
if everyone adheres to the same style.
|
|
|
|
The problem is how to approach this Utopia without a long
|
|
|
|
prescriptive style guide.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-19 14:24:24 -06:00
|
|
|
<p>
|
2009-08-19 17:39:25 -06:00
|
|
|
With Go we take an unusual
|
2009-08-19 14:24:24 -06:00
|
|
|
approach and let the machine
|
|
|
|
take care of most formatting issues.
|
|
|
|
A program, <code>gofmt</code>, reads a Go program
|
|
|
|
and emits the source in a standard style of indentation
|
|
|
|
and vertical alignment, retaining and if necessary
|
|
|
|
reformatting comments.
|
|
|
|
If you want to know how to handle some new layout
|
|
|
|
situation, run <code>gofmt</code>; if the answer doesn't
|
|
|
|
seem right, fix the program (or file a bug), don't work around it.
|
|
|
|
</p>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<p>
|
2009-08-19 14:24:24 -06:00
|
|
|
As an example, there's no need to spend time lining up
|
|
|
|
the comments on the fields of a structure.
|
|
|
|
<code>Gofmt</code> will do that for you. Given the
|
|
|
|
declaration
|
2009-07-31 12:41:30 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-19 14:24:24 -06:00
|
|
|
<pre>
|
|
|
|
type T struct {
|
|
|
|
name string; // name of the object
|
|
|
|
value int; // its value
|
|
|
|
}
|
|
|
|
</pre>
|
2009-07-31 12:41:30 -06:00
|
|
|
|
|
|
|
<p>
|
2009-08-19 14:24:24 -06:00
|
|
|
<code>gofmt</code> will make the columns line up:
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-19 14:24:24 -06:00
|
|
|
<pre>
|
|
|
|
type T struct {
|
|
|
|
name string; // name of the object
|
|
|
|
value int; // its value
|
|
|
|
}
|
|
|
|
</pre>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<p>
|
2009-08-19 14:24:24 -06:00
|
|
|
All code in the libraries has been formatted with <code>gofmt</code>.
|
|
|
|
<font color=red>TODO</font>
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
2009-08-19 14:24:24 -06:00
|
|
|
Some formatting details remain. Very briefly:
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-19 14:24:24 -06:00
|
|
|
<dl>
|
|
|
|
<dt>Indentation</dt>
|
|
|
|
<dd>We use tabs for indentation and <code>gofmt</code> emits them by default.
|
|
|
|
Use spaces if you must.
|
|
|
|
</dd>
|
|
|
|
<dt>Line length</dt>
|
|
|
|
<dd>
|
|
|
|
Go has 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.
|
|
|
|
</dd>
|
|
|
|
<dt>Parentheses</dt>
|
|
|
|
<dd>
|
|
|
|
Go needs fewer parentheses: control structures (<code>if</code>,
|
|
|
|
<code>for</code>, <code>switch</code>) do not have parentheses in
|
|
|
|
their syntax.
|
|
|
|
Also, the operator precedence hierarchy is shorter and clearer, so
|
|
|
|
<pre>
|
|
|
|
x<<8 + y<<16
|
|
|
|
</pre>
|
|
|
|
means what the spacing implies.
|
|
|
|
</dd>
|
|
|
|
</dl>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
2009-08-19 14:24:24 -06:00
|
|
|
<h2>Commentary</h2>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<p>
|
|
|
|
Go provides C-style <code>/* */</code> block comments
|
|
|
|
and C++-style <code>//</code> line comments.
|
2009-08-19 17:39:25 -06:00
|
|
|
Line comments are the norm;
|
|
|
|
block comments appear mostly as package comments and
|
|
|
|
are also useful to disable large swaths of code.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-19 17:39:25 -06:00
|
|
|
<p>
|
|
|
|
The program—and web server—<code>godoc</code> processes
|
|
|
|
Go source files to extract documentation about the contents of the
|
|
|
|
package.
|
|
|
|
Comments that appear before top-level declarations, with no intervening newlines,
|
|
|
|
are 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 <code>godoc</code> produces.
|
|
|
|
</p>
|
2009-07-31 18:54:00 -06:00
|
|
|
|
|
|
|
<p>
|
2009-08-19 17:39:25 -06:00
|
|
|
Every package should have a <i>package comment</i>, a block
|
2009-07-31 18:54:00 -06:00
|
|
|
comment preceding the package clause.
|
2009-08-19 17:39:25 -06:00
|
|
|
For multi-file packages, the package comment only needs to be
|
|
|
|
present in one file, and any one will do.
|
|
|
|
The package comment should introduce the package and
|
2009-07-31 18:54:00 -06:00
|
|
|
provide information relevant to the package as a whole.
|
2009-08-19 17:39:25 -06:00
|
|
|
It will appear first on the <code>godoc</code> page and
|
|
|
|
should set up the detailed documentation that follows.
|
2009-07-31 18:54:00 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
/*
|
|
|
|
The regexp package 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
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
2009-08-19 17:39:25 -06:00
|
|
|
If the package is simple, the package comment can be brief.
|
2009-07-31 18:54:00 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
// The path package implements utility routines for
|
|
|
|
// manipulating slash-separated filename paths.
|
|
|
|
</pre>
|
|
|
|
|
2009-06-25 10:38:35 -06:00
|
|
|
<p>
|
2009-08-19 17:39:25 -06:00
|
|
|
Comments do not need extra formatting such as banners of stars.
|
|
|
|
The generated output may not even be presented in a fixed-width font, so don't depend
|
|
|
|
on spacing for alignment—<code>godoc</code>, like <code>gofmt</code>,
|
|
|
|
takes care of that.
|
|
|
|
Finally, the comments are uninterpreted plain text, so HTML and other
|
|
|
|
annotations such as <code>_this_</code> will reproduce <i>verbatim</i> and should
|
|
|
|
not be used.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
2009-08-19 17:39:25 -06:00
|
|
|
Inside a package, any comment immediately preceding a top-level declaration
|
|
|
|
serves as a <i>doc comment</i> for that declaration.
|
2009-06-25 10:38:35 -06:00
|
|
|
Every exported (capitalized) name in a program should
|
2009-08-19 17:39:25 -06:00
|
|
|
have a doc comment.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
2009-08-19 17:39:25 -06:00
|
|
|
Doc comments work best as complete English sentences, which allow
|
|
|
|
a wide variety of automated presentations.
|
2009-06-25 10:38:35 -06:00
|
|
|
The first sentence should be a one-sentence summary that
|
|
|
|
starts with the name being declared:
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
2009-08-19 17:39:25 -06:00
|
|
|
// Compile parses a regular expression and returns, if successful, a Regexp
|
|
|
|
// object that can be used to match against text.
|
|
|
|
func Compile(str string) (regexp *Regexp, error os.Error) {
|
2009-06-25 10:38:35 -06:00
|
|
|
</pre>
|
|
|
|
|
2009-07-31 18:54:00 -06:00
|
|
|
<p>
|
|
|
|
Go's declaration syntax allows grouping of declarations.
|
2009-08-19 17:39:25 -06:00
|
|
|
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.
|
2009-07-31 18:54:00 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
2009-08-19 17:39:25 -06:00
|
|
|
// Error codes returned by failures to parse an expression.
|
|
|
|
var (
|
|
|
|
ErrInternal = os.NewError("internal error");
|
|
|
|
ErrUnmatchedLpar = os.NewError("unmatched '('");
|
|
|
|
ErrUnmatchedRpar = os.NewError("unmatched ')'");
|
2009-07-31 18:54:00 -06:00
|
|
|
...
|
|
|
|
)
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
2009-08-19 17:39:25 -06:00
|
|
|
Even for private names, grouping can also indicate relationships between items,
|
|
|
|
such as the fact that a set of variables is controlled by a mutex.
|
2009-07-31 18:54:00 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
var (
|
2009-08-03 15:07:19 -06:00
|
|
|
countLock sync.Mutex;
|
2009-07-31 18:54:00 -06:00
|
|
|
inputCount uint32;
|
|
|
|
outputCount uint32;
|
|
|
|
errorCount uint32;
|
|
|
|
)
|
|
|
|
</pre>
|
|
|
|
|
2009-06-25 10:38:35 -06:00
|
|
|
<h2 id="names">Names</h2>
|
|
|
|
|
2009-08-20 16:39:41 -06:00
|
|
|
<p>
|
|
|
|
Names are as important in Go as in any other language.
|
|
|
|
In some cases they even have semantic effect: for instance,
|
|
|
|
the visibility of a name outside a package is determined by whether its
|
|
|
|
first character is an upper case letter,
|
|
|
|
while methods are looked up by name alone (although the type must match too).
|
|
|
|
It's therefore worth spending a little time talking about naming conventions
|
|
|
|
in Go programs.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<h3 id="package-names">Package names</h3>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<p>
|
2009-08-20 16:39:41 -06:00
|
|
|
When a package is imported, the package name becomes an accessor for the
|
|
|
|
contents. After
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-20 16:39:41 -06:00
|
|
|
<pre>
|
|
|
|
import "bytes"
|
|
|
|
</pre>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<p>
|
2009-08-20 16:39:41 -06:00
|
|
|
the importing package can talk about <code>bytes.Buffer</code>. It's
|
|
|
|
helpful if everyone using the package can use the same name to refer to
|
|
|
|
its contents, which implies that the package name should be good:
|
|
|
|
short, concise, evocative. By convention, packages are given
|
|
|
|
lower case, single-word names; there should be no need for underscores
|
|
|
|
or mixedCaps.
|
|
|
|
Err on the side of brevity, since everyone using your
|
|
|
|
package will be typing that name.
|
|
|
|
And don't worry about collisions <i>a priori</i>.
|
|
|
|
The package name is only the default name for imports; it need not be unique
|
|
|
|
across all source code, and in the rare case of a collision the
|
|
|
|
importing package can choose a different name to use locally.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Another convention is that the package name is the base name of
|
|
|
|
its source directory;
|
|
|
|
the package in <code>src/pkg/container/vector</code>
|
2009-07-06 16:15:56 -06:00
|
|
|
is installed as <code>"container/vector"</code> but has name <code>vector</code>,
|
2009-06-25 10:38:35 -06:00
|
|
|
not <code>container_vector</code> and not <code>containerVector</code>.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
2009-08-20 16:39:41 -06:00
|
|
|
The importer of a package will use the name to refer to its contents
|
|
|
|
(the <code>import .</code> notation is intended mostly for tests and other
|
|
|
|
unusual situations), and exported names in the package can use that fact
|
|
|
|
to avoid stutter.
|
|
|
|
For instance, the buffered reader type in the <code>bufio</code> package is called <code>Reader</code>,
|
|
|
|
not <code>BufReader</code>, because users see it as <code>bufio.Reader</code>,
|
|
|
|
which is a clear, concise name.
|
|
|
|
Moreover,
|
|
|
|
because imported entities are always addressed with their package name, <code>bufio.Reader</code>
|
|
|
|
does not conflict with <code>io.Reader</code>.
|
|
|
|
Use the package structure to help you choose good names.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
2009-08-20 16:39:41 -06:00
|
|
|
Another short example is <code>once.Do</code>;
|
|
|
|
<code>once.Do(setup)</code> reads well and would not be improved by
|
|
|
|
writing <code>once.DoOrWaitUntilDone(setup)</code>.
|
|
|
|
Long names don't automatically make things more readable.
|
|
|
|
If the name represents something intricate or subtle, it's usually better
|
|
|
|
to write a helpful doc comment than to attempt to put all the information
|
|
|
|
into the name.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-20 16:39:41 -06:00
|
|
|
<h3 id="interface-names">Interface names</h3>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<p>
|
2009-08-20 16:39:41 -06:00
|
|
|
By convention, one-method interfaces are named by
|
2009-06-25 10:38:35 -06:00
|
|
|
the method name plus the -er suffix: <code>Reader</code>,
|
2009-08-20 16:39:41 -06:00
|
|
|
<code>Writer</code>, <code>Formatter</code> etc.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
2009-08-20 16:39:41 -06:00
|
|
|
There are a number of such names and it's productive to honor them and the function
|
|
|
|
names they capture.
|
|
|
|
<code>Read</code>, <code>Write</code>, <code>Close</code>, <code>Flush</code>,
|
|
|
|
<code>String</code> and so on have
|
2009-06-25 10:38:35 -06:00
|
|
|
canonical signatures and meanings. To avoid confusion,
|
|
|
|
don't give your method one of those names unless it
|
|
|
|
has the same signature and meaning.
|
|
|
|
Conversely, if your type implements a method with the
|
|
|
|
same meaning as a method on a well-known type,
|
2009-08-20 16:39:41 -06:00
|
|
|
give it the same name and signature;
|
|
|
|
call your string-converter method <code>String</code> not <code>ToString</code>.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-20 16:39:41 -06:00
|
|
|
<h3 id="mixed-caps">MixedCaps</h3>
|
|
|
|
|
2009-06-25 10:38:35 -06:00
|
|
|
<p>
|
2009-08-20 16:39:41 -06:00
|
|
|
Finally, the convention in Go is to used <code>MixedCaps</code>
|
|
|
|
or <code>mixedCaps</code> rather than underscores to write
|
|
|
|
multiword names.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-08-20 16:39:41 -06:00
|
|
|
|
2009-06-25 10:38:35 -06:00
|
|
|
<h2 id="idioms">Idioms</h2>
|
|
|
|
|
2009-08-13 12:29:05 -06:00
|
|
|
<h3 id="struct-allocation">Allocate using literals</h3>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<p>
|
2009-08-13 12:29:05 -06:00
|
|
|
A struct literal is an expression that creates a
|
|
|
|
new instance each time it is evaluated. The address of such
|
2009-08-19 14:24:24 -06:00
|
|
|
an expression points to a fresh instance each time.
|
2009-08-13 12:29:05 -06:00
|
|
|
Use such expressions to avoid the repetition of filling
|
2009-06-25 10:38:35 -06:00
|
|
|
out a data structure.
|
|
|
|
</p>
|
|
|
|
|
2009-07-31 18:54:00 -06:00
|
|
|
<pre>
|
2009-08-13 12:29:05 -06:00
|
|
|
length := Point{x, y}.Abs();
|
2009-08-19 14:24:24 -06:00
|
|
|
</pre>
|
2009-08-13 12:29:05 -06:00
|
|
|
|
2009-08-19 14:24:24 -06:00
|
|
|
<pre>
|
2009-07-31 18:54:00 -06:00
|
|
|
// Prepare RPCMessage to send to server
|
|
|
|
rpc := &RPCMessage {
|
|
|
|
Version: 1,
|
|
|
|
Header: &RPCHeader {
|
|
|
|
Id: nextId(),
|
|
|
|
Signature: sign(body),
|
|
|
|
Method: method,
|
|
|
|
},
|
|
|
|
Body: body,
|
|
|
|
};
|
|
|
|
</pre>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<h3 id="buffer-slice">Use parallel assignment to slice a buffer</h3>
|
|
|
|
|
|
|
|
<pre>
|
2009-07-31 18:54:00 -06:00
|
|
|
header, body, checksum := buf[0:20], buf[20:n-4], buf[n-4:n];
|
2009-06-25 10:38:35 -06:00
|
|
|
</pre>
|
|
|
|
|
|
|
|
<h2 id="control-flow">Control Flow</h2>
|
|
|
|
|
|
|
|
<h3 id="else">Omit needless else bodies</h3>
|
|
|
|
|
|
|
|
<p>
|
2009-07-31 12:41:30 -06:00
|
|
|
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>,
|
2009-07-06 16:15:56 -06:00
|
|
|
<code>goto</code>, or <code>return</code>—omit the <code>else</code>.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
f, err := os.Open(name, os.O_RDONLY, 0);
|
|
|
|
if err != nil {
|
|
|
|
return err;
|
|
|
|
}
|
|
|
|
codeUsing(f);
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<h3 id="switch">Switch</h3>
|
|
|
|
|
|
|
|
<p>
|
2009-07-06 16:15:56 -06:00
|
|
|
Go's <code>switch</code> is more general than C's.
|
2009-08-19 14:24:24 -06:00
|
|
|
When an <code>if</code>-<code>else</code>-<code>if</code>-<code>else</code>
|
|
|
|
chain has three or more bodies,
|
2009-06-25 10:38:35 -06:00
|
|
|
or an <code>if</code> condition has a long list of alternatives,
|
2009-07-06 16:15:56 -06:00
|
|
|
it will be clearer if rewritten as a <code>switch</code>.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<a href="/src/pkg/http/url.go">go/src/pkg/http/url.go</a>:
|
|
|
|
<pre>
|
|
|
|
func unhex(c byte) byte {
|
|
|
|
switch {
|
|
|
|
case '0' <= c && c <= '9':
|
|
|
|
return c - '0'
|
|
|
|
case 'a' <= c && c <= 'f':
|
|
|
|
return c - 'a' + 10
|
|
|
|
case 'A' <= c && c <= 'F':
|
|
|
|
return c - 'A' + 10
|
|
|
|
}
|
|
|
|
return 0
|
|
|
|
}
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<a href="/src/pkg/http/url.go">go/src/pkg/http/url.go</a>:
|
|
|
|
<pre>
|
|
|
|
func shouldEscape(c byte) bool {
|
|
|
|
switch c {
|
2009-07-06 16:15:56 -06:00
|
|
|
case ' ', '?', '&', '=', '#', '+', '%':
|
2009-06-25 10:38:35 -06:00
|
|
|
return true
|
|
|
|
}
|
|
|
|
return false
|
|
|
|
}
|
|
|
|
</pre>
|
|
|
|
|
2009-07-06 16:15:56 -06:00
|
|
|
<a href="/src/pkg/bytes/bytes.go">go/src/pkg/bytes/bytes.go</a>:
|
|
|
|
<pre>
|
2009-07-31 18:54:00 -06:00
|
|
|
// Compare returns an integer comparing the two byte arrays
|
|
|
|
// lexicographically.
|
2009-07-06 16:15:56 -06:00
|
|
|
// The result will be 0 if a==b, -1 if a < b, and +1 if a > b
|
|
|
|
func Compare(a, b []byte) int {
|
|
|
|
for i := 0; i < len(a) && i < len(b); i++ {
|
|
|
|
switch {
|
|
|
|
case a[i] > b[i]:
|
|
|
|
return 1
|
|
|
|
case a[i] < b[i]:
|
|
|
|
return -1
|
|
|
|
}
|
|
|
|
}
|
|
|
|
switch {
|
|
|
|
case len(a) < len(b):
|
|
|
|
return -1
|
|
|
|
case len(a) > len(b):
|
|
|
|
return 1
|
|
|
|
}
|
|
|
|
return 0
|
|
|
|
}
|
|
|
|
</pre>
|
|
|
|
|
2009-06-25 10:38:35 -06:00
|
|
|
<h2 id="functions">Functions</h2>
|
|
|
|
|
|
|
|
<h3 id="omit-wrappers">Omit needless wrappers</h3>
|
|
|
|
|
|
|
|
<p>
|
2009-07-06 16:15:56 -06:00
|
|
|
Functions are great for factoring out common code, but
|
|
|
|
if a function is only called once,
|
|
|
|
ask whether it is necessary,
|
2009-06-25 10:38:35 -06:00
|
|
|
especially if it is just a short wrapper around another function.
|
2009-07-06 16:15:56 -06:00
|
|
|
This style is rampant in C++ code: wrappers
|
2009-06-25 10:38:35 -06:00
|
|
|
call wrappers that call wrappers that call wrappers.
|
2009-07-06 16:15:56 -06:00
|
|
|
This style hinders people trying to understand the program,
|
2009-06-25 10:38:35 -06:00
|
|
|
not to mention computers trying to execute it.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<h3 id="multiple-returns">Return multiple values</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
If a function must return multiple values, it can
|
|
|
|
do so directly.
|
2009-07-06 16:15:56 -06:00
|
|
|
There is no need to pass a pointer to a return value.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<h2 id="errors">Errors</h2>
|
|
|
|
|
2009-07-31 12:41:30 -06:00
|
|
|
<h3 id="error-returns">Return <code>os.Error</code>, not <code>bool</code></h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
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.
|
|
|
|
</p>
|
|
|
|
|
2009-06-25 10:38:35 -06:00
|
|
|
<h3 id="handle-errors-first">Handle errors first</h3>
|
|
|
|
|
|
|
|
<p>
|
2009-07-06 16:15:56 -06:00
|
|
|
Error cases tend to be simpler than non-error cases,
|
2009-06-25 10:38:35 -06:00
|
|
|
and it helps readability when the non-error flow
|
|
|
|
of control is always down the page.
|
2009-08-19 14:24:24 -06:00
|
|
|
Also, error cases tend to end in <code>return</code> statements,
|
2009-06-25 10:38:35 -06:00
|
|
|
so that there is <a href="#else">no need for an explicit else</a>.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
2009-07-06 16:15:56 -06:00
|
|
|
if len(name) == 0 {
|
2009-07-31 12:41:30 -06:00
|
|
|
return os.EINVAL;
|
2009-07-06 16:15:56 -06:00
|
|
|
}
|
|
|
|
if IsDir(name) {
|
2009-07-31 12:41:30 -06:00
|
|
|
return os.EISDIR;
|
2009-07-06 16:15:56 -06:00
|
|
|
}
|
2009-06-25 10:38:35 -06:00
|
|
|
f, err := os.Open(name, os.O_RDONLY, 0);
|
|
|
|
if err != nil {
|
2009-07-31 12:41:30 -06:00
|
|
|
return err;
|
2009-06-25 10:38:35 -06:00
|
|
|
}
|
|
|
|
codeUsing(f);
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<h3 id="error-context">Return structured errors</h3>
|
|
|
|
|
2009-08-03 15:07:19 -06:00
|
|
|
Implementations of <code>os.Error</code> should
|
|
|
|
describe the error and provide context.
|
2009-06-25 10:38:35 -06:00
|
|
|
For example, <code>os.Open</code> returns an <code>os.PathError</code>:
|
|
|
|
|
|
|
|
<a href="/src/pkg/os/file.go">/src/pkg/os/file.go</a>:
|
|
|
|
<pre>
|
2009-08-03 15:07:19 -06:00
|
|
|
// PathError records an error and the operation and
|
|
|
|
// file path that caused it.
|
|
|
|
type PathError struct {
|
|
|
|
Op string;
|
|
|
|
Path string;
|
|
|
|
Error Error;
|
|
|
|
}
|
|
|
|
|
|
|
|
func (e *PathError) String() string {
|
2009-08-13 12:29:05 -06:00
|
|
|
return e.Op + " " + e.Path + ": " + e.Error.String();
|
2009-08-03 15:07:19 -06:00
|
|
|
}
|
2009-06-25 10:38:35 -06:00
|
|
|
</pre>
|
|
|
|
|
2009-08-13 12:29:05 -06:00
|
|
|
<p>
|
2009-06-25 10:38:35 -06:00
|
|
|
<code>PathError</code>'s <code>String</code> formats
|
2009-08-03 15:07:19 -06:00
|
|
|
the error nicely, including the operation and file name
|
|
|
|
tha failed; just printing the error generates a
|
|
|
|
message, such as
|
2009-08-13 12:29:05 -06:00
|
|
|
</p>
|
2009-06-25 10:38:35 -06:00
|
|
|
<pre>
|
2009-08-03 15:07:19 -06:00
|
|
|
open /etc/passwx: no such file or directory
|
2009-06-25 10:38:35 -06:00
|
|
|
</pre>
|
2009-08-13 12:29:05 -06:00
|
|
|
<p>
|
2009-08-03 15:07:19 -06:00
|
|
|
that is useful even if printed far from the call that
|
|
|
|
triggered it.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Callers that care about the precise error details can
|
|
|
|
use a type switch or a type guard to look for specific
|
2009-08-13 12:29:05 -06:00
|
|
|
errors and extract details. For <code>PathErrors</code>
|
|
|
|
this might include examining the internal <code>Error</code>
|
|
|
|
to see if it is <code>os.EPERM</code> or <code>os.ENOENT</code>,
|
|
|
|
for instance.
|
2009-08-03 15:07:19 -06:00
|
|
|
</p>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
<h2 id="types">Programmer-defined types</h2>
|
|
|
|
|
|
|
|
<h3 id="constructors">Use <code>NewTypeName</code> for constructors</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The constructor for the type <code>pkg.MyType</code> should
|
|
|
|
be named <code>pkg.NewMyType</code> and should return <code>*pkg.MyType</code>.
|
|
|
|
The implementation of <code>NewTypeName</code> often uses the
|
2009-08-13 12:29:05 -06:00
|
|
|
<a href="#struct-allocation">struct allocation idiom</a>.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<a href="xxx">go/src/pkg/os/file.go</a>:
|
|
|
|
<pre>
|
|
|
|
func NewFile(fd int, name string) *File {
|
|
|
|
if file < 0 {
|
|
|
|
return nil
|
|
|
|
}
|
|
|
|
return &File{fd, name, nil, 0}
|
|
|
|
}
|
|
|
|
</pre>
|
|
|
|
|
2009-08-19 14:24:24 -06:00
|
|
|
<p>Packages that export only a single type can
|
2009-06-25 10:38:35 -06:00
|
|
|
shorten <code>NewTypeName</code> to <code>New</code>;
|
2009-07-06 16:15:56 -06:00
|
|
|
the vector constructor is
|
2009-06-25 10:38:35 -06:00
|
|
|
<code>vector.New</code>, not <code>vector.NewVector</code>.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
A type that is intended to be allocated
|
|
|
|
as part of a larger struct may have an <code>Init</code> method
|
|
|
|
that must be called explicitly.
|
|
|
|
Conventionally, the <code>Init</code> method returns
|
|
|
|
the object being initialized, to make the constructor trivial:
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<a href="xxx">go/src/pkg/container/vector/vector.go</a>:
|
|
|
|
<pre>
|
|
|
|
func New(len int) *Vector {
|
|
|
|
return new(Vector).Init(len)
|
|
|
|
}
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<h3 id="zero-value">Make the zero value meaningful</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
In Go, newly allocated memory and newly declared variables are zeroed.
|
|
|
|
If a type is intended to be allocated without using a constructor
|
|
|
|
(for example, as part of a larger struct or declared as a local variable),
|
|
|
|
define the meaning of the zero value and arrange for that meaning
|
|
|
|
to be useful.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
For example, <code>sync.Mutex</code> does not
|
|
|
|
have an explicit constructor or <code>Init</code> method.
|
|
|
|
Instead, the zero value for a <code>sync.Mutex</code>
|
|
|
|
is defined to be an unlocked mutex.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<h2 id="interfaces">Interfaces</h2>
|
|
|
|
|
|
|
|
<h3 id="accept-interface-values">Accept interface values</h3>
|
|
|
|
|
|
|
|
buffered i/o takes a Reader, not an os.File. XXX
|
|
|
|
|
|
|
|
<h3 id="return-interface-values">Return interface values</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
If a type exists only to implement an interface
|
|
|
|
and has no exported methods beyond that interface,
|
|
|
|
there is no need to publish the type itself.
|
|
|
|
Instead, write a constructor that returns an interface value.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
For example, both <code>crc32.NewIEEE()</code> and <code>adler32.New()</code>
|
|
|
|
return type <code>hash.Hash32</code>.
|
|
|
|
Substituting the CRC-32 algorithm for Adler-32 in a Go program
|
|
|
|
requires only changing the constructor call:
|
2009-07-06 16:15:56 -06:00
|
|
|
the rest of the code is unaffected by the change of algorithm.
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
2009-07-06 16:15:56 -06:00
|
|
|
<h3 id="asdf">Use interface adapters to expand an implementation</h3>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
XXX
|
|
|
|
|
2009-07-06 16:15:56 -06:00
|
|
|
<h3 id="fdsa">Use anonymous fields to incorporate an implementation</h3>
|
2009-06-25 10:38:35 -06:00
|
|
|
|
|
|
|
XXX
|
|
|
|
|
|
|
|
<h2>Data-Driven Programming</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
tables
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
XXX struct tags for marshalling.
|
|
|
|
template
|
|
|
|
eventually datafmt
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<h2>Concurrency</h2>
|
|
|
|
|
|
|
|
<h3 id="share-memory">Share memory by communicating</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Do not communicate by sharing memory;
|
|
|
|
instead, share memory by communicating.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
XXX, more here.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<h2>Testing</h2>
|
|
|
|
|
|
|
|
<h3 id="no-abort">Run tests to completion</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Tests should not stop early just because one case has misbehaved.
|
|
|
|
If at all possible, let tests continue, in order to characterize the
|
|
|
|
problem in more detail.
|
|
|
|
For example, it is more useful for a test to report that <code>isPrime</code>
|
2009-08-19 14:24:24 -06:00
|
|
|
gives the wrong answer for 4, 8, 16 and 32 than to report
|
|
|
|
that <code>isPrime</code> gives the wrong answer for 4 and therefore
|
2009-06-25 10:38:35 -06:00
|
|
|
no more tests were run.
|
2009-08-19 14:24:24 -06:00
|
|
|
XXX
|
|
|
|
test bottom up
|
|
|
|
test runs top to bottom
|
|
|
|
how to use gotest
|
|
|
|
XXX
|
2009-06-25 10:38:35 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
<h3 id="good-errors">Print useful errors when tests fail</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
If a test fails, print a concise message explaining the context,
|
|
|
|
what happened, and what was expected.
|
|
|
|
Many testing environments encourage causing the
|
|
|
|
program to crash, but stack traces and core dumps
|
|
|
|
have low signal to noise ratios and require reconstructing
|
|
|
|
the situation from scratch.
|
|
|
|
The programmer who triggers the test failure may be someone
|
|
|
|
editing the code months later or even someone editing a different
|
|
|
|
package on which the code depends.
|
|
|
|
Time invested writing a good error message now pays off when
|
|
|
|
the test breaks later.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<h3 id="data-driven-tests">Use data-driven tests</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Many tests reduce to running the same code multiple times,
|
|
|
|
with different input and expected output.
|
|
|
|
Instead of using cut and paste to write this code,
|
|
|
|
create a table of test cases and write a single test that
|
|
|
|
iterates over the table.
|
|
|
|
Once the table is written, you might find that it
|
|
|
|
serves well as input to multiple tests. For example,
|
|
|
|
a single table of encoded/decoded pairs can be
|
|
|
|
used by both <code>TestEncoder</code> and <code>TestDecoder</code>.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
This data-driven style dominates in the Go package tests.
|
|
|
|
<br>
|
|
|
|
<!-- search for for.*range here -->
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<h3 id="reflect.DeepEqual">Use reflect.DeepEqual to compare complex values</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The <code>reflect.DeepEqual</code> function tests
|
|
|
|
whether two complex data structures have equal values.
|
|
|
|
If a function returns a complex data structure,
|
|
|
|
<code>reflect.DeepEqual</code> combined with table-driven testing
|
|
|
|
makes it easy to check that the return value is
|
|
|
|
exactly as expected.
|
|
|
|
</p>
|
|
|
|
|
2009-08-13 12:29:05 -06:00
|
|
|
<h2 id="be-consistent">Be consistent</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
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.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
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.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Consider <code>for</code> loops.
|
|
|
|
Traditionally, a loop over <code>n</code>
|
|
|
|
elements begins:
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
for i := 0; i < n; i++ {
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Much of the time, the loop could run in the opposite order
|
|
|
|
and still be correct:
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
for i := n-1; i >= 0; i-- {
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The convention
|
|
|
|
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.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Loop direction is just one
|
|
|
|
programming decision that must be made
|
|
|
|
consistently; others include
|
|
|
|
formatting, naming variables and methods,
|
|
|
|
whether a type
|
|
|
|
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:
|
|
|
|
what does the code do?
|
|
|
|
Moreover, internal consistency is important not only within a single file,
|
|
|
|
but also within the the surrounding source files.
|
|
|
|
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.
|
|
|
|
</p>
|
|
|
|
|
2009-06-25 10:38:35 -06:00
|
|
|
</div>
|
|
|
|
</body>
|
|
|
|
</html>
|