mirror of
https://github.com/golang/go
synced 2024-11-12 06:30:21 -07:00
ee3e97c778
R=rsc DELTA=2 (0 added, 0 deleted, 2 changed) OCL=35759 CL=35761
1939 lines
56 KiB
HTML
1939 lines
56 KiB
HTML
<!-- Effective Go -->
|
|
|
|
<!-- interfaces; cast,conversion, type assertion; embedding; errors; testing; initialization -->
|
|
|
|
<h2 id="introduction">Introduction</h2>
|
|
|
|
<p>
|
|
Go is a new language. Although it borrows ideas from
|
|
existing languages,
|
|
it has unusual properties that make effective Go programs
|
|
different in character from programs in its relatives.
|
|
A straightforward translation of a C++ or Java program into Go
|
|
is unlikely to produce a satisfactory result—Java programs
|
|
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
|
|
and idioms.
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
This document gives tips for writing clear, idiomatic Go code.
|
|
It augments the <a href="go_spec.html">language specification</a>
|
|
and the <a href="go_tutorial.html">tutorial</a>, both of which you
|
|
should read first.
|
|
</p>
|
|
|
|
<h3 id="read">Examples</h3>
|
|
|
|
<p>
|
|
The <a href="http://s2/?dir=//depot2/go/src/pkg">Go package sources</a>
|
|
are intended to serve not
|
|
only as the core library but also as examples of how to
|
|
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.
|
|
</p>
|
|
|
|
|
|
<h2 id="formatting">Formatting</h2>
|
|
|
|
<p>
|
|
Formatting issues are the most contentious
|
|
but the least consequential.
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
With Go we take an unusual
|
|
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>
|
|
|
|
<p>
|
|
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
|
|
</p>
|
|
|
|
<pre>
|
|
type T struct {
|
|
name string; // name of the object
|
|
value int; // its value
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
<code>gofmt</code> will make the columns line up.
|
|
</p>
|
|
|
|
<pre>
|
|
type T struct {
|
|
name string; // name of the object
|
|
value int; // its value
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
All code in the libraries has been formatted with <code>gofmt</code>.
|
|
</p>
|
|
|
|
|
|
<p>
|
|
Some formatting details remain. Very briefly,
|
|
</p>
|
|
|
|
<dl>
|
|
<dt>Indentation</dt>
|
|
<dd>We use tabs for indentation and <code>gofmt</code> emits them by default.
|
|
Use spaces only 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 require 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>
|
|
|
|
<h2>Commentary</h2>
|
|
|
|
<p>
|
|
Go provides C-style <code>/* */</code> block comments
|
|
and C++-style <code>//</code> line comments.
|
|
Line comments are the norm;
|
|
block comments appear mostly as package comments and
|
|
are also useful to disable large swaths of code.
|
|
</p>
|
|
|
|
<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>
|
|
|
|
<p>
|
|
Every package should have a <i>package comment</i>, a block
|
|
comment preceding the package clause.
|
|
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
|
|
provide information relevant to the package as a whole.
|
|
It will appear first on the <code>godoc</code> page and
|
|
should set up the detailed documentation that follows.
|
|
</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>
|
|
If the package is simple, the package comment can be brief.
|
|
</p>
|
|
|
|
<pre>
|
|
// The path package implements utility routines for
|
|
// manipulating slash-separated filename paths.
|
|
</pre>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
Inside a package, any comment immediately preceding a top-level declaration
|
|
serves as a <i>doc comment</i> for that declaration.
|
|
Every exported (capitalized) name in a program should
|
|
have a doc comment.
|
|
</p>
|
|
|
|
<p>
|
|
Doc comments work best as complete English sentences, which allow
|
|
a wide variety of automated presentations.
|
|
The first sentence should be a one-sentence summary that
|
|
starts with the name being declared.
|
|
</p>
|
|
|
|
<pre>
|
|
// 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) {
|
|
</pre>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<pre>
|
|
// Error codes returned by failures to parse an expression.
|
|
var (
|
|
ErrInternal = os.NewError("internal error");
|
|
ErrUnmatchedLpar = os.NewError("unmatched '('");
|
|
ErrUnmatchedRpar = os.NewError("unmatched ')'");
|
|
...
|
|
)
|
|
</pre>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<pre>
|
|
var (
|
|
countLock sync.Mutex;
|
|
inputCount uint32;
|
|
outputCount uint32;
|
|
errorCount uint32;
|
|
)
|
|
</pre>
|
|
|
|
<h2 id="names">Names</h2>
|
|
|
|
<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.
|
|
It's therefore worth spending a little time talking about naming conventions
|
|
in Go programs.
|
|
</p>
|
|
|
|
|
|
<h3 id="package-names">Package names</h3>
|
|
|
|
<p>
|
|
When a package is imported, the package name becomes an accessor for the
|
|
contents. After
|
|
</p>
|
|
|
|
<pre>
|
|
import "bytes"
|
|
</pre>
|
|
|
|
<p>
|
|
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.
|
|
In any case, confusion is rare because the file name in the import
|
|
defines which version is being used.
|
|
</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>
|
|
is installed as <code>"container/vector"</code> but has name <code>vector</code>,
|
|
not <code>container_vector</code> and not <code>containerVector</code>.
|
|
</p>
|
|
|
|
<p>
|
|
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>.
|
|
Similarly, the function to make new instances of <code>vector.Vector</code>
|
|
—which is the definition of a <em>constructor</em> in Go—would
|
|
normally be called <code>NewVector</code> but since
|
|
<code>Vector</code> is the only type exported by the package, and since the
|
|
package is called <code>vector</code>, it's called just <code>New</code>.
|
|
Clients of the package see that as <code>vector.New</code>.
|
|
Use the package structure to help you choose good names.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3 id="interface-names">Interface names</h3>
|
|
|
|
<p>
|
|
By convention, one-method interfaces are named by
|
|
the method name plus the -er suffix: <code>Reader</code>,
|
|
<code>Writer</code>, <code>Formatter</code> etc.
|
|
</p>
|
|
|
|
<p>
|
|
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
|
|
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,
|
|
give it the same name and signature;
|
|
call your string-converter method <code>String</code> not <code>ToString</code>.
|
|
</p>
|
|
|
|
<h3 id="mixed-caps">MixedCaps</h3>
|
|
|
|
<p>
|
|
Finally, the convention in Go is to use <code>MixedCaps</code>
|
|
or <code>mixedCaps</code> rather than underscores to write
|
|
multiword names.
|
|
</p>
|
|
|
|
<h2 id="semicolons">Semicolons</h2>
|
|
|
|
<p>
|
|
Go needs fewer semicolons between statements than do other C variants.
|
|
Semicolons are never required at the top level.
|
|
Also they are separators, not terminators, so they
|
|
can be left off the last element of a statement or declaration list,
|
|
a convenience
|
|
for one-line <code>funcs</code> and the like.
|
|
</p>
|
|
|
|
<pre>
|
|
func CopyInBackground(dst, src chan Item) {
|
|
go func() { for { dst <- <-src } }()
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
In fact, semicolons can be omitted at the end of any "StatementList" in the
|
|
grammar, which includes things like cases in <code>switch</code>
|
|
statements.
|
|
</p>
|
|
|
|
<pre>
|
|
switch {
|
|
case a < b:
|
|
return -1
|
|
case a == b:
|
|
return 0
|
|
case a > b:
|
|
return 1
|
|
}
|
|
|
|
</pre>
|
|
|
|
<p>
|
|
The grammar accepts an empty statement after any statement list, which
|
|
means a terminal semicolon is always OK. As a result,
|
|
it's fine to put semicolons everywhere you'd put them in a
|
|
C program—they would be fine after those return statements,
|
|
for instance—but they can often be omitted.
|
|
By convention, they're always left off top-level declarations (for
|
|
instance, they don't appear after the closing brace of <code>struct</code>
|
|
declarations, or of <code>funcs</code> for that matter)
|
|
and often left off one-liners. But within functions, place them
|
|
as you see fit.
|
|
</p>
|
|
|
|
<h2 id="control-structures">Control structures</h2>
|
|
|
|
<p>
|
|
The control structures of Go are related to those of C but different
|
|
in important ways.
|
|
There is no <code>do</code> or <code>while</code> loop, only a
|
|
slightly generalized
|
|
<code>for</code>;
|
|
<code>switch</code> is more flexible;
|
|
<code>if</code> and <code>switch</code> accept an optional
|
|
initialization statement like that of <code>for</code>;
|
|
and there are new control structures including a type switch and a
|
|
multiway communications multiplexer, <code>select</code>.
|
|
The syntax is also slightly different:
|
|
parentheses are not required
|
|
and the bodies must always be brace-delimited.
|
|
</p>
|
|
|
|
<h3 id="if">If</h3>
|
|
|
|
<p>
|
|
In Go a simple <code>if</code> looks like this:
|
|
</p>
|
|
<pre>
|
|
if x > 0 {
|
|
return y
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
Mandatory braces encourage writing simple <code>if</code> statements
|
|
on multiple lines. It's good style to do so anyway,
|
|
especially when the body contains a control statement such as a
|
|
<code>return</code> or <code>break</code>.
|
|
</p>
|
|
|
|
<p>
|
|
Since <code>if</code> and <code>switch</code> accept an initialization
|
|
statement, it's common to see one used to set up a local variable.
|
|
</p>
|
|
|
|
<pre>
|
|
if err := file.Chmod(0664); err != nil {
|
|
log.Stderr(err)
|
|
}
|
|
</pre>
|
|
|
|
<p id="else">
|
|
In the Go libraries, you'll find that
|
|
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>—the unnecessary
|
|
<code>else</code> is omitted.
|
|
</p>
|
|
|
|
<pre>
|
|
f, err := os.Open(name, os.O_RDONLY, 0);
|
|
if err != nil {
|
|
return err;
|
|
}
|
|
codeUsing(f);
|
|
</pre>
|
|
|
|
<p>
|
|
This is a example of a common situation where code must analyze a
|
|
sequence of error possibilities. The code reads well if the
|
|
successful flow of control runs down the page, eliminating error cases
|
|
as they arise. Since error cases tend to end in <code>return</code>
|
|
statements, the resulting code needs no <code>else</code> statements.
|
|
</p>
|
|
|
|
<pre>
|
|
f, err := os.Open(name, os.O_RDONLY, 0);
|
|
if err != nil {
|
|
return err;
|
|
}
|
|
d, err := f.Stat();
|
|
if err != nil {
|
|
return err;
|
|
}
|
|
codeUsing(f, d);
|
|
</pre>
|
|
|
|
|
|
<h3 id="for">For</h3>
|
|
|
|
<p>
|
|
The Go <code>for</code> loop is similar to—but not the same as—C's.
|
|
It unifies <code>for</code>
|
|
and <code>while</code> and there is no <code>do-while</code>.
|
|
There are three forms, only one of which has semicolons.
|
|
</p>
|
|
<pre>
|
|
// Like a C for
|
|
for init; condition; post { }
|
|
|
|
// Like a C while
|
|
for condition { }
|
|
|
|
// Like a C for(;;)
|
|
for { }
|
|
</pre>
|
|
|
|
<p>
|
|
Short declarations make it easy to declare the index variable right in the loop.
|
|
</p>
|
|
<pre>
|
|
sum := 0;
|
|
for i := 0; i < 10; i++ {
|
|
sum += i
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
If you're looping over an array, slice, string, or map a <code>range</code> clause can set
|
|
it all up for you.
|
|
</p>
|
|
<pre>
|
|
var m map[string] int;
|
|
sum := 0;
|
|
for _, value := range m { // key is unused
|
|
sum += value
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
For strings, the <code>range</code> does more of the work for you, breaking out individual
|
|
characters by parsing the UTF-8 (erroneous encodings consume one byte and produce the
|
|
replacement rune U+FFFD). The loop
|
|
</p>
|
|
<pre>
|
|
for pos, char := range "日本語" {
|
|
fmt.Printf("character %c starts at byte position %d\n", char, pos)
|
|
}
|
|
</pre>
|
|
<p>
|
|
prints
|
|
</p>
|
|
<pre>
|
|
character 日 starts at byte position 0
|
|
character 本 starts at byte position 3
|
|
character 語 starts at byte position 6
|
|
</pre>
|
|
|
|
<p>
|
|
Finally, since Go has no comma operator and <code>++</code> and <code>--</code>
|
|
are statements not expressions, if you want to run multiple variables in a <code>for</code>
|
|
you should use parallel assignment.
|
|
</p>
|
|
<pre>
|
|
// Reverse a
|
|
for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
|
|
a[i], a[j] = a[j], a[i]
|
|
}
|
|
</pre>
|
|
|
|
<h3 id="switch">Switch</h3>
|
|
|
|
<p>
|
|
Go's <code>switch</code> is more general than C's.
|
|
The expressions need not be constants or even integers,
|
|
the cases are evaluated top to bottom until a match is found,
|
|
and if the <code>switch</code> has no expression it switches on
|
|
<code>true</code>.
|
|
It's therefore possible—and idiomatic—to write an
|
|
<code>if</code>-<code>else</code>-<code>if</code>-<code>else</code>
|
|
chain as a <code>switch</code>.
|
|
</p>
|
|
|
|
<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>
|
|
|
|
<p>
|
|
There is no automatic fall through, but cases can be presented
|
|
in comma-separated lists.
|
|
<pre>
|
|
func shouldEscape(c byte) bool {
|
|
switch c {
|
|
case ' ', '?', '&', '=', '#', '+', '%':
|
|
return true
|
|
}
|
|
return false
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
Here's a comparison routine for byte arrays that uses two
|
|
<code>switch</code> statements:
|
|
<pre>
|
|
// Compare returns an integer comparing the two byte arrays
|
|
// lexicographically.
|
|
// 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>
|
|
|
|
<p>
|
|
A switch can also be used to discover the dynamic type of an interface
|
|
variable. Such a <em>type switch</em> uses the syntax of a type
|
|
assertion with the keyword <code>type</code> inside the parentheses.
|
|
If the switch declares a variable in the expression, the variable will
|
|
have the corresponding type in each clause.
|
|
</p>
|
|
<pre>
|
|
switch t := interfaceValue.(type) {
|
|
default:
|
|
fmt.Printf("unexpected type");
|
|
case bool:
|
|
fmt.Printf("boolean %t\n", t);
|
|
case int:
|
|
fmt.Printf("integer %d\n", t);
|
|
case *bool:
|
|
fmt.Printf("pointer to boolean %t\n", *t);
|
|
case *int:
|
|
fmt.Printf("pointer to integer %d\n", *t);
|
|
}
|
|
</pre>
|
|
|
|
<h2 id="functions">Functions</h2>
|
|
|
|
<h3 id="multiple-returns">Multiple return values</h3>
|
|
|
|
<p>
|
|
One of Go's unusual properties is that functions and methods
|
|
can return multiple values. This feature can be used to
|
|
improve on a couple of clumsy idioms in C programs: in-band
|
|
error returns (<code>-1</code> for <code>EOF</code> for example)
|
|
and modifying an argument.
|
|
</p>
|
|
|
|
<p>
|
|
In C, a write error is signaled by a negative byte count with the
|
|
error code secreted away in a volatile location.
|
|
In Go, <code>Write</code>
|
|
can return a byte count <i>and</i> an error: "Yes, you wrote some
|
|
bytes but not all of them because you filled the device".
|
|
The signature of <code>*File.Write</code> in package <code>os</code> is:
|
|
</p>
|
|
|
|
<pre>
|
|
func (file *File) Write(b []byte) (n int, err Error)
|
|
</pre>
|
|
|
|
<p>
|
|
and as the documentation says, it returns the number of bytes
|
|
written and a non-nil <code>Error</code> when <code>n</code>
|
|
<code>!=</code> <code>len(b)</code>.
|
|
This is a common style; see the section on error handling for more examples.
|
|
</p>
|
|
|
|
<p>
|
|
A similar approach obviates the need to pass a pointer to a return
|
|
value to simulate a reference parameter.
|
|
Here's a simple-minded function to
|
|
grab a number from a position in a byte array, returning the number
|
|
and the next position.
|
|
</p>
|
|
|
|
<pre>
|
|
func nextInt(b []byte, i int) (int, int) {
|
|
for ; i < len(b) && !isDigit(b[i]); i++ {
|
|
}
|
|
x := 0;
|
|
for ; i < len(b) && isDigit(b[i]); i++ {
|
|
x = x*10 + int(b[i])-'0'
|
|
}
|
|
return x, i;
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
You could use it to scan the numbers in an input array <code>a</code> like this:
|
|
</p>
|
|
|
|
<pre>
|
|
for i := 0; i < len(a); {
|
|
x, i = nextInt(a, i);
|
|
fmt.Println(x);
|
|
}
|
|
</pre>
|
|
|
|
<h3 id="named-results">Named result parameters</h3>
|
|
|
|
<p>
|
|
The return or result "parameters" of a Go function can be given names and
|
|
used as regular variables, just like the incoming parameters.
|
|
When named, they are initialized to the zero values for their types when
|
|
the function begins; if the function executes a <code>return</code> statement
|
|
with no arguments, the current values of the result parameters are
|
|
used as the returned values.
|
|
</p>
|
|
|
|
<p>
|
|
The names are not mandatory but they can make code shorter and clearer:
|
|
they're documentation.
|
|
If we name the results of <code>nextInt</code> it becomes
|
|
obvious which returned <code>int</code>
|
|
is which.
|
|
</p>
|
|
|
|
<pre>
|
|
func nextInt(b []byte, pos int) (value, nextPos int) {
|
|
</pre>
|
|
|
|
<p>
|
|
Because named results are initialized and tied to an unadorned return, they can simplify
|
|
as well as clarify. Here's a version
|
|
of <code>io.ReadFull</code> that uses them well:
|
|
</p>
|
|
|
|
<pre>
|
|
func ReadFull(r Reader, buf []byte) (n int, err os.Error) {
|
|
for len(buf) > 0 && err != nil {
|
|
var nr int;
|
|
nr, err = r.Read(buf);
|
|
n += nr;
|
|
buf = buf[nr:len(buf)];
|
|
}
|
|
return;
|
|
}
|
|
</pre>
|
|
|
|
<h2 id="data">Data</h2>
|
|
|
|
<h3 id="allocation_new">Allocation with <code>new()</code></h3>
|
|
|
|
<p>
|
|
Go has two allocation primitives, <code>new()</code> and <code>make()</code>.
|
|
They do different things and apply to different types, which can be confusing,
|
|
but the rules are simple.
|
|
Let's talk about <code>new()</code> first.
|
|
It's a built-in function essentially the same as its namesakes
|
|
in other languages: it allocates zeroed storage for a new item of type
|
|
<code>T</code> and returns its address, a value of type <code>*T</code>.
|
|
In Go terminology, it returns a pointer to a newly allocated zero value of type
|
|
<code>T</code>.
|
|
</p>
|
|
|
|
<p>
|
|
Since the memory returned by <code>new()</code> is zeroed, it's helpful to arrange that the
|
|
zeroed object can be used without further initialization. This means a user of
|
|
the data structure can create one with <code>new()</code> and get right to
|
|
work.
|
|
For example, the documentation for <code>bytes.Buffer</code> states that
|
|
"the zero value for <code>Buffer</code> is an empty buffer ready to use."
|
|
Similarly, <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>
|
|
|
|
<p>
|
|
The zero-value-is-useful property works transitively. Consider this type declaration.
|
|
</p>
|
|
|
|
<pre>
|
|
type SyncedBuffer struct {
|
|
lock sync.Mutex;
|
|
buffer bytes.Buffer;
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
Values of type <code>SyncedBuffer</code> are also ready to use immediately upon allocation
|
|
or just declaration. In this snippet, both <code>p</code> and <code>v</code> will work
|
|
correctly without further arrangement.
|
|
</p>
|
|
|
|
<pre>
|
|
p := new(SyncedBuffer); // type *SyncedBuffer
|
|
var v SyncedBuffer; // type SyncedBuffer
|
|
</pre>
|
|
|
|
<h3 id="composite_literals">Constructors and composite literals</h3>
|
|
|
|
<p>
|
|
Sometimes the zero value isn't good enough and an initializing
|
|
constructor is necessary, as in this example derived from
|
|
package <code>os</code>.
|
|
</p>
|
|
|
|
<pre>
|
|
func NewFile(fd int, name string) *File {
|
|
if fd < 0 {
|
|
return nil
|
|
}
|
|
f := new(File);
|
|
f.fd = fd;
|
|
f.name = name;
|
|
f.error = nil;
|
|
f.dirinfo = nil;
|
|
f.nepipe = 0;
|
|
return f;
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
There's a lot of boilerplate in there. We can simplify it
|
|
using a <i>composite literal</i>, which is
|
|
an expression that creates a
|
|
new instance each time it is evaluated.
|
|
</p>
|
|
|
|
|
|
<pre>
|
|
func NewFile(fd int, name string) *File {
|
|
if file < 0 {
|
|
return nil
|
|
}
|
|
f := File{fd, name, nil, 0};
|
|
return &f;
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
Note that it's perfectly OK to return the address of a local variable;
|
|
the storage associated with the variable survives after the function
|
|
returns.
|
|
In fact, taking the address of a composite literal
|
|
allocates a fresh instance each time it is evaluated,
|
|
so we can combine these last two lines.
|
|
</p>
|
|
|
|
<pre>
|
|
return &File{fd, name, nil, 0};
|
|
</pre>
|
|
|
|
<p>
|
|
The fields of a composite literal are laid out in order and must all be present.
|
|
However, by labeling the elements explicitly as <i>field</i><code>:</code><i>value</i>
|
|
pairs, the initializers can appear in any
|
|
order, with the missing ones left as their respective zero values. Thus we could say
|
|
</p>
|
|
|
|
<pre>
|
|
return &File{fd: fd, name: name}
|
|
</pre>
|
|
|
|
<p>
|
|
As a limiting case, if a composite literal contains no fields at all, it creates
|
|
a zero value for the type. These two expressions are equivalent.
|
|
</p>
|
|
|
|
<pre>
|
|
new(File)
|
|
&File{}
|
|
</pre>
|
|
|
|
<p>
|
|
Composite literals can also be created for arrays, slices, and maps,
|
|
with the field labels being indices or map keys as appropriate.
|
|
In these examples, the initializations work regardless of the values of <code>EnoError</code>,
|
|
<code>Eio</code>, and <code>Einval</code>, as long as they are distinct.
|
|
</p>
|
|
|
|
<pre>
|
|
a := [...]string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"};
|
|
s := []string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"};
|
|
m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"};
|
|
</pre>
|
|
|
|
<h3 id="allocation_make">Allocation with <code>make()</code></h3>
|
|
|
|
<p>
|
|
Back to allocation.
|
|
The built-in function <code>make(T, </code><i>args</i><code>)</code> serves
|
|
a purpose different from <code>new(T)</code>.
|
|
It creates slices, maps, and channels only, and it returns an initialized (not zero)
|
|
value of type <code>T</code>, not <code>*T</code>.
|
|
The reason for the distinction
|
|
is that these three types are, under the covers, references to data structures that
|
|
must be initialized before use.
|
|
A slice, for example, is a three-item descriptor
|
|
containing a pointer to the data (inside an array), the length, and the
|
|
capacity; until those items are initialized, the slice is <code>nil</code>.
|
|
For slices, maps, and channels,
|
|
<code>make</code> initializes the internal data structure and prepares
|
|
the value for use.
|
|
For instance,
|
|
</p>
|
|
|
|
<pre>
|
|
make([]int, 10, 100)
|
|
</pre>
|
|
|
|
<p>
|
|
allocates an array of 100 ints and then creates a slice
|
|
structure with length 10 and a capacity of 100 pointing at the first
|
|
10 elements of the array.
|
|
(When making a slice, the capacity can be omitted; see the section on slices
|
|
for more information.)
|
|
In contrast, <code>new([]int)</code> returns a pointer to a newly allocated, zeroed slice
|
|
structure, that is, a pointer to a <code>nil</code> slice value.
|
|
|
|
<p>
|
|
These examples illustrate the difference between <code>new()</code> and
|
|
<code>make()</code>.
|
|
</p>
|
|
|
|
<pre>
|
|
var p *[]int = new([]int); // allocates slice structure; *p == nil; rarely useful
|
|
var v []int = make([]int, 100); // v now refers to a new array of 100 ints
|
|
|
|
// Unnecessarily complex:
|
|
var p *[]int = new([]int);
|
|
*p = make([]int, 100, 100);
|
|
|
|
// Idiomatic:
|
|
v := make([]int, 100);
|
|
</pre>
|
|
|
|
<p>
|
|
Remember that <code>make()</code> applies only to maps, slices and channels.
|
|
To obtain an explicit pointer allocate with <code>new()</code>.
|
|
</p>
|
|
|
|
<h3 id="arrays">Arrays</h3>
|
|
|
|
<p>
|
|
Arrays are useful when planning the detailed layout of memory and sometimes
|
|
can help avoid allocation but primarily
|
|
they are a building block for slices, the subject of the next section.
|
|
To lay the foundation for that topic, here are a few words about arrays.
|
|
</p>
|
|
|
|
<p>
|
|
There are major differences between the ways arrays work in Go and C.
|
|
In Go,
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
Arrays are values. Assigning one array to another copies all the elements.
|
|
</li>
|
|
<li>
|
|
In particular, if you pass an array to a function, it
|
|
will receive a <i>copy</i> of the array, not a pointer to it.
|
|
<li>
|
|
The size of an array is part of its type. The types <code>[10]int</code>
|
|
and <code>[20]int</code> are distinct.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
The value property can be useful but also expensive; if you want C-like behavior and efficiency,
|
|
you can pass a pointer to the array.
|
|
</p>
|
|
|
|
<pre>
|
|
func Sum(a *[]float) (sum float) {
|
|
for _, v := range a {
|
|
sum += v
|
|
}
|
|
return
|
|
}
|
|
|
|
array := [...]float{7.0, 8.5, 9.1};
|
|
x := sum(&array); // Note the explicit address-of operator
|
|
</pre>
|
|
|
|
<p>
|
|
But even this style isn't idiomatic Go. Slices are.
|
|
</p>
|
|
|
|
<h3 id="slices">Slices</h3>
|
|
|
|
<p>
|
|
Slices wrap arrays to give a more general, powerful, and convenient
|
|
interface to sequences of data. Except for items with explicit
|
|
dimension such as transformation matrices, most array programming in
|
|
Go is done with slices rather than simple arrays.
|
|
</p>
|
|
<p>
|
|
Slices are <i>reference types</i>, which means that if you assign one
|
|
slice to another, both refer to the same underlying array. For
|
|
instance, if a function takes a slice argument, changes it makes to
|
|
the elements of the slice will be visible to the caller, analogous to
|
|
passing a pointer to the underlying array. A <code>Read</code>
|
|
function can therefore accept a slice argument rather than a (pointer
|
|
to an) array and a count; the length within the slice sets an upper
|
|
limit of how much data to read. Here is the signature of the
|
|
<code>Read</code> method of the <code>File</code> type in package
|
|
<code>os</code>:
|
|
</p>
|
|
<pre>
|
|
func (file *File) Read(buf []byte) (n int, err os.Error)
|
|
</pre>
|
|
<p>
|
|
The method returns the number of bytes read and an error value, if
|
|
any. To read into the first 32 bytes of a larger buffer
|
|
<code>b</code>, <i>slice</i> (here used as a verb) the buffer.
|
|
</p>
|
|
<pre>
|
|
n, err := f.Read(buf[0:32]);
|
|
</pre>
|
|
<p>
|
|
Such slicing is common and efficient. In fact, leaving efficiency aside for
|
|
the moment, this snippet would also read the first 32 bytes of the buffer.
|
|
</p>
|
|
<pre>
|
|
var n int;
|
|
var err os.Error;
|
|
for i := 0; i < 32; i++ {
|
|
nbytes, e := f.Read(buf[i:i+1]);
|
|
if nbytes == 0 || e != nil {
|
|
err = e;
|
|
break;
|
|
}
|
|
n += nbytes;
|
|
}
|
|
</pre>
|
|
<p>
|
|
The length of a slice may be changed as long as it still fits within
|
|
the limits of the underlying array; just assign it to a slice of
|
|
itself. The <i>capacity</i> of a slice, accessible by the built-in
|
|
function <code>cap</code>, reports the maximum length the slice may
|
|
assume. Here is a function to append data to a slice. If the data
|
|
exceeds the capacity, the slice is reallocated. The
|
|
resulting slice is returned. The function uses the fact that
|
|
<code>len</code> and <code>cap</code> are legal when applied to the
|
|
<code>nil</code> slice, and return 0.
|
|
</p>
|
|
<pre>
|
|
func Append(slice, data[]byte) []byte {
|
|
l := len(slice);
|
|
if l + len(data) > cap(slice) { // reallocate
|
|
// Allocate double what's needed, for future growth.
|
|
newSlice := make([]byte, (l+len(data))*2);
|
|
// Copy data (could use bytes.Copy()).
|
|
for i, c := range slice {
|
|
newSlice[i] = c
|
|
}
|
|
slice = newSlice;
|
|
}
|
|
slice = slice[0:l+len(data)];
|
|
for i, c := range data {
|
|
slice[l+i] = c
|
|
}
|
|
return slice;
|
|
}
|
|
</pre>
|
|
<p>
|
|
We must return the slice afterwards because, although <code>Append</code>
|
|
can modify the elements of <code>slice</code>, the slice itself (the run-time data
|
|
structure holding the pointer, length, and capacity) is passed by value.
|
|
</p>
|
|
|
|
|
|
<h3 id="maps">Maps</h3>
|
|
|
|
<p>
|
|
Maps are a convenient and powerful built-in data structure to associate
|
|
values of different types.
|
|
The key can be of type that implements equality, such as integers,
|
|
floats, strings, pointers, and interfaces (as long as the dynamic type
|
|
supports equality), but not structs, arrays or slices
|
|
because those types do not have equality defined upon them.
|
|
Like slices, maps are a reference type. If you pass a map to a function
|
|
that changes the contents of the map, the changes will be visible
|
|
in the caller.
|
|
</p>
|
|
<p>
|
|
Maps can be constructed using the usual composite literal syntax
|
|
with colon-separated key-value pairs,
|
|
so it's easy to build them during initialization.
|
|
</p>
|
|
<pre>
|
|
var timeZone = map[string] int {
|
|
"UTC": 0*60*60,
|
|
"EST": -5*60*60,
|
|
"CST": -6*60*60,
|
|
"MST": -7*60*60,
|
|
"PST": -8*60*60,
|
|
}
|
|
</pre>
|
|
<p>
|
|
Assigning and fetching map values looks syntactically just like
|
|
doing the same for arrays except that the index doesn't need to
|
|
be an integer. An attempt to fetch a map value with a key that
|
|
is not present in the map will cause the program to crash, but
|
|
there is a way to do so safely using a multiple assignment.
|
|
</p>
|
|
<pre>
|
|
var seconds int;
|
|
var ok bool;
|
|
seconds, ok = timeZone[tz]
|
|
</pre>
|
|
<p>
|
|
For obvious reasons this is called the “comma ok” idiom.
|
|
In this example, if <code>tz</code> is present, <code>seconds</code>
|
|
will be set appropriately and <code>ok</code> will be true; if not,
|
|
<code>seconds</code> will be set to zero and <code>ok</code> will
|
|
be false.
|
|
Here's a function that puts it together:
|
|
</p>
|
|
<pre>
|
|
func offset(tz string) int {
|
|
if seconds, ok := timeZone[tz]; ok {
|
|
return seconds
|
|
}
|
|
log.Stderr("unknown time zone", tz);
|
|
return 0;
|
|
}
|
|
</pre>
|
|
<p>
|
|
To test for presence in the map without worrying about the actual value,
|
|
you can use the <em>blank identifier</em>, a simple underscore (<code>_</code>).
|
|
The blank identifier can be assigned or declared with any value of any type, with the
|
|
value discarded harmlessly. For testing presence in a map, use the blank
|
|
identifier in place of the usual variable for the value.
|
|
</p>
|
|
<pre>
|
|
_, present := timeZone[tz];
|
|
</pre>
|
|
<p>
|
|
To delete a map entry, turn the multiple assignment around by placing
|
|
an extra boolean on the right; if the boolean is false, the entry
|
|
is deleted. It's safe to do this even if the key is already absent
|
|
from the map.
|
|
</p>
|
|
<pre>
|
|
timeZone["PDT"] = 0, false; // Now on Standard Time
|
|
</pre>
|
|
<h3 id="printing">Printing</h3>
|
|
|
|
<p>
|
|
Formatted printing in Go uses a style similar to C's <code>printf</code>
|
|
family but is richer and more general. The functions live in the <code>fmt</code>
|
|
package and have capitalized names: <code>fmt.Printf</code>, <code>fmt.Fprintf</code>,
|
|
<code>fmt.Sprintf</code> and so on. The string functions (<code>Sprintf</code> etc.)
|
|
return a string rather than filling in a provided buffer.
|
|
</p>
|
|
<p>
|
|
You don't need to provide a format string. For each of <code>Printf</code>,
|
|
<code>fmt.Fprintf</code> and <code>fmt.Sprintf</code> there is another pair
|
|
of functions, for instance <code>Print</code> and <code>Println</code>.
|
|
These functions do not take a format string but instead generate a default
|
|
format for each argument. The <code>ln</code> version also inserts a blank
|
|
between arguments if neither is a string and appends a newline to the output.
|
|
In this example each line produces the same output.
|
|
</p>
|
|
<pre>
|
|
fmt.Printf("Hello %d\n", 23);
|
|
fmt.Fprint(os.Stdout, "Hello ", 23, "\n");
|
|
fmt.Println(fmt.Sprint("Hello ", 23));
|
|
</pre>
|
|
<p>
|
|
Recall that <code>fmt.Fprint</code> and friends take as a first argument any object
|
|
that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code>
|
|
and <code>os.Stderr</code> are familiar instances.
|
|
</p>
|
|
<p>
|
|
Here things start to diverge from C. First, the numeric formats such as <code>%d</code>
|
|
do not take flags for signedness or size; instead, the printing routines use the
|
|
type of the argument to decide these properties.
|
|
</p>
|
|
<pre>
|
|
var x uint64 = 1<<64 - 1;
|
|
fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x));
|
|
</pre>
|
|
<p>
|
|
prints
|
|
</p>
|
|
<pre>
|
|
18446744073709551615 ffffffffffffffff; -1 -1
|
|
</pre>
|
|
<p>
|
|
If you just want the default conversion, such as decimal for integers, you can use
|
|
the catchall format <code>%v</code> (for “value”); the result is exactly
|
|
what <code>Print</code> and <code>Println</code> would produce.
|
|
Moreover, that format can print <em>any</em> value, even arrays, structs, and
|
|
maps. Here is a print statement for the time zone map defined in the previous section.
|
|
</p>
|
|
<pre>
|
|
fmt.Printf("%v\n", timeZone); // or just fmt.Println(timeZone);
|
|
</pre>
|
|
<p>
|
|
which gives output
|
|
</p>
|
|
<pre>
|
|
map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200]
|
|
</pre>
|
|
<p>
|
|
For maps the keys may be output in any order, of course.
|
|
When printing a struct, the modified format <code>%+v</code> annotates the
|
|
fields of the structure with their names, and for any value the alternate
|
|
format <code>%#v</code> prints the value in full Go syntax.
|
|
</p>
|
|
<pre>
|
|
type T struct {
|
|
a int;
|
|
b float;
|
|
c string;
|
|
}
|
|
t := &T{ 7, -2.35, "abc\tdef" };
|
|
fmt.Printf("%v\n", t);
|
|
fmt.Printf("%+v\n", t);
|
|
fmt.Printf("%#v\n", t);
|
|
fmt.Printf("%#v\n", timeZone);
|
|
</pre>
|
|
<p>
|
|
prints
|
|
</p>
|
|
<pre>
|
|
&{7 -2.35 abc def}
|
|
&{a:7 b:-2.35 c:abc def}
|
|
&main.T{a:7, b:-2.35, c:"abc\tdef"}
|
|
map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
|
|
</pre>
|
|
<p>
|
|
(Note the ampersands.)
|
|
That quoted string format is also available through <code>%q</code> when
|
|
applied to a value of type <code>string</code> or <code>[]byte</code>;
|
|
the alternate format <code>%#q</code> will use backquotes instead if possible.
|
|
Also, <code>%x</code> works on strings and arrays of bytes as well as on integers,
|
|
generating a long hexadecimal string, and with
|
|
a space in the format (<code>% x</code>) it puts spaces between the bytes.
|
|
</p>
|
|
<p>
|
|
Another handy format is <code>%T</code>, which prints the <em>type</em> of a value.
|
|
<pre>
|
|
fmt.Printf("%T\n", timeZone);
|
|
</pre>
|
|
<p>
|
|
prints
|
|
</p>
|
|
<pre>
|
|
map[string] int
|
|
</pre>
|
|
<p>
|
|
If you want to control the default format for a custom type, all that's required is to define
|
|
a method <code>String() string</code> on the type.
|
|
For our simple type <code>T</code>, that might look like this.
|
|
</p>
|
|
<pre>
|
|
func (t *T) String() string {
|
|
return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c);
|
|
}
|
|
fmt.Printf("%v\n", t);
|
|
</pre>
|
|
<p>
|
|
to print in the format
|
|
</p>
|
|
<pre>
|
|
7/-2.35/"abc\tdef"
|
|
</pre>
|
|
<p>
|
|
Our <code>String()</code> method is able to call <code>Sprintf</code> because the
|
|
print routines are fully reentrant and can be used recursively.
|
|
We can even go one step further and pass a print routine's arguments directly to another such routine.
|
|
The signature of <code>Printf</code> uses the <code>...</code>
|
|
type for its final argument to specify that an arbitrary number of parameters can appear
|
|
after the format.
|
|
</p>
|
|
<pre>
|
|
func Printf(format string, v ...) (n int, errno os.Error) {
|
|
</pre>
|
|
<p>
|
|
Within the function <code>Printf</code>, <code>v</code> is a variable that can be passed,
|
|
for instance, to another print routine. Here is the implementation of the
|
|
function <code>log.Stderr</code> we used above. It passes its arguments directly to
|
|
<code>fmt.Sprintln</code> for the actual formatting.
|
|
</p>
|
|
<pre>
|
|
// Stderr is a helper function for easy logging to stderr. It is analogous to Fprint(os.Stderr).
|
|
func Stderr(v ...) {
|
|
stderr.Output(2, fmt.Sprintln(v)); // Output takes parameters (int, string)
|
|
}
|
|
</pre>
|
|
<p>
|
|
There's even more to printing than we've covered here. See the <code>godoc</code> documentation
|
|
for package <code>fmt</code> for the details.
|
|
</p>
|
|
|
|
<h2>Methods</h2>
|
|
|
|
<h3 id="pointers_vs_values">Pointers vs. Values</h3>
|
|
<p>
|
|
Methods can be defined for any named type except pointers and interfaces;
|
|
the receiver does not have to be a struct.
|
|
<p>
|
|
In the discussion of slices above, we wrote an <code>Append</code>
|
|
function. We can define it as a method on slices instead. To do
|
|
this, we first declare a named type to which we can bind the method, and
|
|
then make the receiver for the method a value of that type.
|
|
</p>
|
|
<pre>
|
|
type ByteSlice []byte
|
|
|
|
func (slice ByteSlice) Append(data []byte) []slice {
|
|
// Body exactly the same as above
|
|
}
|
|
</pre>
|
|
<p>
|
|
This still requires the method to return the updated slice. We can
|
|
eliminate that clumsiness by redefining the method to take a
|
|
<i>pointer</i> to a <code>ByteSlice</code> as its receiver, so the
|
|
method can overwrite the caller's slice.
|
|
</p>
|
|
<pre>
|
|
func (p *ByteSlice) Append(data []byte) {
|
|
slice := *p;
|
|
// Body as above, without the return.
|
|
*p = slice;
|
|
}
|
|
</pre>
|
|
<p>
|
|
In fact, we can do even better. If we modify our function so it looks
|
|
like a standard <code>Write</code> method, like this,
|
|
</p>
|
|
<pre>
|
|
func (p *ByteSlice) Write(data []byte) (n int, err os.Error) {
|
|
slice := *p;
|
|
// Again as above.
|
|
*p = slice;
|
|
return len(data), nil)
|
|
}
|
|
</pre>
|
|
<p>
|
|
then the type <code>*ByteSlice</code> satisfies the standard interface
|
|
<code>io.Writer</code>, which is handy. For instance, we can
|
|
print into one.
|
|
</p>
|
|
<pre>
|
|
var b ByteSlice;
|
|
fmt.Fprintf(&b, "This hour has %d days\n", 7);
|
|
</pre>
|
|
<p>
|
|
We pass the address of a <code>ByteSlice</code>
|
|
because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>.
|
|
The rule about pointers vs. values for receivers is that value methods
|
|
can be invoked on pointers and values, but pointer methods can only be
|
|
invoked on pointers. This is because pointer methods can modify the
|
|
receiver; invoking them on a copy of the value would cause those
|
|
modifications to be discarded.
|
|
</p>
|
|
<p>
|
|
By the way, the idea of using <code>Write</code> on a slice of bytes
|
|
is implemented by <code>bytes.Buffer</code>.
|
|
</p>
|
|
|
|
<h2 id="interfaces_and_types">Interfaces and other types</h2>
|
|
|
|
<h3 id="interfaces">Interfaces</h3>
|
|
<p>
|
|
Interfaces in Go provide a way to specify the behavior of an
|
|
object: if something can do <em>this</em>, then it can be used
|
|
<em>here</em>. We've seen a couple of simple examples already;
|
|
custom printers can be implemented by a <code>String</code> method
|
|
while <code>Fprintf</code> can generate output to anything
|
|
with a <code>Write</code> method.
|
|
Interfaces with only one or two methods are common in Go code, and are
|
|
usually given a name derived from the method, such as <code>io.Writer</code>
|
|
for something that implements <code>Write</code>.
|
|
</p>
|
|
<p>
|
|
A type can implement multiple interfaces.
|
|
For instance, a collection can be sorted
|
|
by the routines in package <code>sort</code> if it implements
|
|
<code>sort.Interface</code>, which contains <code>Len()</code>,
|
|
<code>Less(i, j int)</code>, and <code>Swap(i, j int)</code>,
|
|
and it could also have a custom formatter.
|
|
In this contrived example <code>Sequence</code> satisfies both.
|
|
</p>
|
|
<pre>
|
|
type Sequence []int
|
|
|
|
// Methods required by sort.Interface.
|
|
func (s Sequence) Len() int {
|
|
return len(s)
|
|
}
|
|
func (s Sequence) Less(i, j int) bool {
|
|
return s[i] < s[j]
|
|
}
|
|
func (s Sequence) Swap(i, j int) {
|
|
s[i], s[j] = s[j], s[i]
|
|
}
|
|
|
|
// Method for printing - sorts the elements before printing.
|
|
func (s Sequence) String() string {
|
|
sort.Sort(s);
|
|
str := "[";
|
|
for i, elem := range s {
|
|
if i > 0 {
|
|
str += " "
|
|
}
|
|
str += fmt.Sprint(elem);
|
|
}
|
|
return str + "]";
|
|
}
|
|
</pre>
|
|
|
|
<h3 id="conversions">Conversions</h3>
|
|
|
|
<p>
|
|
The <code>String</code> method of <code>Sequence</code> is recreating the
|
|
work that <code>Sprint</code> already does for slices. We can share the
|
|
effort if we convert the <code>Sequence</code> to a plain
|
|
<code>[]int</code> before calling <code>Sprint</code>.
|
|
</p>
|
|
<pre>
|
|
func (s Sequence) String() string {
|
|
sort.Sort(s);
|
|
return fmt.Sprint([]int(s));
|
|
}
|
|
</pre>
|
|
<p>
|
|
The conversion causes <code>s</code> to be treated as an ordinary slice
|
|
and therefore receive the default formatting.
|
|
Without the conversion, <code>Sprint</code> would find the
|
|
<code>String</code> method of <code>Sequence</code> and recur indefinitely.
|
|
Because the two types (<code>Sequence</code> and <code>[]int</code>)
|
|
are the same if we ignore the type name, it's legal to convert between them.
|
|
The conversion doesn't create a new value, it just temporarily acts
|
|
as though the existing value has a new type.
|
|
(There are other legal conversions, such as from integer to float, that
|
|
do create a new value.)
|
|
</p>
|
|
<p>
|
|
It's an idiom of Go code to convert the
|
|
type of an expression to access a different
|
|
set of methods. As an example, we could use the existing
|
|
type <code>sort.IntArray</code> to reduce the entire example
|
|
to this:
|
|
</p>
|
|
<pre>
|
|
type Sequence []int
|
|
|
|
// Method for printing - sorts the elements before printing
|
|
func (s Sequence) String() string {
|
|
sort.IntArray(s).Sort();
|
|
return fmt.Sprint([]int(s))
|
|
}
|
|
</pre>
|
|
<p>
|
|
Now, instead of having <code>Sequence</code> implement multiple
|
|
interfaces (sorting and printing), we're using the ability of a data item to be
|
|
converted to multiple types (<code>Sequence</code>, <code>sort.IntArray</code>
|
|
and <code>[]int</code>), each of which does some part of the job.
|
|
That's more unusual in practice but can be effective.
|
|
</p>
|
|
|
|
<h3 id="generality">Generality</h3>
|
|
<p>
|
|
If a type exists only to implement an interface
|
|
and has no exported methods beyond that interface,
|
|
there is no need to export the type itself.
|
|
Exporting just the interface makes it clear that
|
|
it's the behavior that matters, not the implementation,
|
|
and that other implementations with different properties
|
|
can mirror the behavior of the original type.
|
|
It also avoids the need to repeat the documentation
|
|
on every instance of a common method.
|
|
</p>
|
|
<p>
|
|
In such cases, the constructor should return an interface value
|
|
rather than the implementing type.
|
|
As an example, in the hash libraries
|
|
both <code>crc32.NewIEEE()</code> and <code>adler32.New()</code>
|
|
return the interface type <code>hash.Hash32</code>.
|
|
Substituting the CRC-32 algorithm for Adler-32 in a Go program
|
|
requires only changing the constructor call;
|
|
the rest of the code is unaffected by the change of algorithm.
|
|
</p>
|
|
<p>
|
|
A similar approach allows the streaming cipher algorithms
|
|
in the <code>crypto/block</code> package to be
|
|
separated from the block ciphers they chain together.
|
|
By analogy to the <code>bufio</code> package,
|
|
they wrap a <code>Cipher</code> interface
|
|
and they return <code>hash.Hash</code>,
|
|
<code>io.Reader</code>, or <code>io.Writer</code>
|
|
interface values, not specific implementations.
|
|
</p>
|
|
<p>
|
|
The interface to <code>crypto/block</code> includes:
|
|
</p>
|
|
<pre>
|
|
type Cipher interface {
|
|
BlockSize() int;
|
|
Encrypt(src, dst []byte);
|
|
Decrypt(src, dst []byte);
|
|
}
|
|
|
|
// NewECBDecrypter returns a reader that reads data
|
|
// from r and decrypts it using c in electronic codebook (ECB) mode.
|
|
func NewECBDecrypter(c Cipher, r io.Reader) io.Reader
|
|
|
|
// NewCBCDecrypter returns a reader that reads data
|
|
// from r and decrypts it using c in cipher block chaining (CBC) mode
|
|
// with the initialization vector iv.
|
|
func NewCBCDecrypter(c Cipher, iv []byte, r io.Reader) io.Reader
|
|
</pre>
|
|
<p>
|
|
<code>NewECBDecrypter</code> and <code>NewCBCReader</code> apply not
|
|
just to one specific encryption algorithm and data source but to any
|
|
implementation of the <code>Cipher</code> interface and any
|
|
<code>io.Reader</code>. Because they return <code>io.Reader</code>
|
|
interface values, replacing ECB
|
|
encryption with CBC encryption is a localized change. The constructor
|
|
calls must be edited, but because the code must treat the result only
|
|
as an <code>io.Reader</code>, it won't notice the difference.
|
|
</p>
|
|
|
|
<h3 id="interface_methods">Interfaces and methods</h3>
|
|
<p>
|
|
Since almost anything can have methods attached, almost anything can
|
|
satisfy an interface. One illustrative example is in the <code>http</code>
|
|
package, which defines the <code>Handler</code> interface. Any object
|
|
that implements <code>Handler</code> can serve HTTP requests.
|
|
</p>
|
|
<pre>
|
|
type Handler interface {
|
|
ServeHTTP(*Conn, *Request);
|
|
}
|
|
</pre>
|
|
<p>
|
|
For brevity, let's ignore POSTs and assume HTTP requests are always
|
|
GETs; that simplification does not affect the way the handlers are
|
|
made. Here's a trivial but complete implementation of a handler to
|
|
count the number of times the
|
|
page is visited.
|
|
</p>
|
|
<pre>
|
|
// Simple counter server.
|
|
type Counter struct {
|
|
n int;
|
|
}
|
|
|
|
func (ctr *Counter) ServeHTTP(c *http.Conn, req *http.Request) {
|
|
ctr.n++;
|
|
fmt.Fprintf(c, "counter = %d\n", ctr.n);
|
|
}
|
|
</pre>
|
|
<p>
|
|
(Keeping with our theme, note how <code>Fprintf</code> can print to an HTTP connection.)
|
|
For reference, here's how to set up such a server.
|
|
<pre>
|
|
import "http"
|
|
...
|
|
ctr := new(Counter);
|
|
http.Handle("/counter", ctr);
|
|
</pre>
|
|
<p>
|
|
But why make <code>Counter</code> a struct? An integer is all that's needed.
|
|
(The receiver needs to be a pointer so the increment is visible to the caller.)
|
|
</p>
|
|
<pre>
|
|
// Simpler counter server.
|
|
type Counter int
|
|
|
|
func (ctr *Counter) ServeHTTP(c *http.Conn, req *http.Request) {
|
|
*ctr++;
|
|
fmt.Fprintf(c, "counter = %d\n", *ctr);
|
|
}
|
|
</pre>
|
|
<p>
|
|
What if your program has some internal state that needs to be notified that a page
|
|
has been visited? Tie a channel to the web page.
|
|
</p>
|
|
<pre>
|
|
// A channel that sends a notification on each visit.
|
|
// (Probably want the channel to be buffered.)
|
|
type Chan chan int
|
|
|
|
func (ch Chan) ServeHTTP(c *http.Conn, req *http.Request) {
|
|
ch <- 1;
|
|
fmt.Fprint(c, "notification sent");
|
|
}
|
|
</pre>
|
|
<p>
|
|
Finally, let's say we wanted to present on <code>/args</code> the arguments
|
|
used when invoking the server binary.
|
|
It's easy to write a function to print the arguments:
|
|
</p>
|
|
<pre>
|
|
func ArgServer() {
|
|
for i, s := range os.Args {
|
|
fmt.Println(s);
|
|
}
|
|
}
|
|
</pre>
|
|
<p>
|
|
How do we turn that into an HTTP server? We could make <code>ArgServer</code>
|
|
a method of some type whose value we ignore, but there's a cleaner way.
|
|
Since we can write a method for (almost) any type, we can write a method
|
|
for a function.
|
|
The <code>http</code> package contains this code:
|
|
</p>
|
|
<pre>
|
|
// The HandlerFunc type is an adapter to allow the use of
|
|
// ordinary functions as HTTP handlers. If f is a function
|
|
// with the appropriate signature, HandlerFunc(f) is a
|
|
// Handler object that calls f.
|
|
type HandlerFunc func(*Conn, *Request)
|
|
|
|
// ServeHTTP calls f(c, req).
|
|
func (f HandlerFunc) ServeHTTP(c *Conn, req *Request) {
|
|
f(c, req);
|
|
}
|
|
</pre>
|
|
<p>
|
|
<code>HandlerFunc</code> is a type with a method, <code>ServeHTTP</code>,
|
|
so values of that type can serve HTTP requests. Look at the implementation
|
|
of the method: the receiver is a function, <code>f</code>, and the method
|
|
calls <code>f</code>. That may seem odd but it's no different from, say,
|
|
the receiver being a channel and the method sending on the channel.
|
|
</p>
|
|
<p>
|
|
To make <code>ArgServer</code> into an HTTP server, we first give it the right
|
|
signature.
|
|
</p>
|
|
<pre>
|
|
// Argument server.
|
|
func ArgServer(c *http.Conn, req *http.Request) {
|
|
for i, s := range os.Args {
|
|
fmt.Fprintln(c, s);
|
|
}
|
|
}
|
|
</pre>
|
|
<p>
|
|
<code>ArgServer</code> has same signature as <code>HandlerFunc</code>,
|
|
so the function can be converted to that type to access its methods,
|
|
just as we converted <code>Sequence</code> to <code>[]int</code> earlier.
|
|
The code to set it up is short:
|
|
</p>
|
|
<pre>
|
|
http.Handle("/args", http.HandlerFunc(ArgServer));
|
|
</pre>
|
|
<p>
|
|
When someone visits the page <code>/args</code>,
|
|
the handler installed at that page has type
|
|
<code>HandlerFunc</code> and value <code>ArgServer</code>.
|
|
The HTTP server will invoke the method <code>ServeHTTP</code>
|
|
of that type, with that receiver, which will in turn call
|
|
<code>ArgServer</code> (via the invocation <code>f(c, req)</code>
|
|
inside <code>HandlerFunc.ServeHTTP</code>) and the arguments
|
|
will be displayed.
|
|
</p>
|
|
<p>
|
|
In summary, we have made an HTTP server from a struct, an integer,
|
|
a channel, and a function, all because interfaces are just sets of
|
|
methods, which can be defined for (almost) any type.
|
|
</p>
|
|
|
|
<h2 id="errors">Errors</h2>
|
|
|
|
<p>
|
|
Library routines must often return some sort of error indication to
|
|
the caller. As mentioned earlier, Go's multivalue return makes it
|
|
easy to return a detailed error description alongside the normal
|
|
return value. By convention, errors have type <code>os.Error</code>,
|
|
a simple interface.
|
|
</p>
|
|
<pre>
|
|
type Error interface {
|
|
String() string;
|
|
}
|
|
</pre>
|
|
<p>
|
|
A library writer is free to implement this interface with a
|
|
richer model under the covers, making it possible not only
|
|
to see the error but also to provide some context.
|
|
For example, <code>os.Open</code> returns an <code>os.PathError</code>.
|
|
</p>
|
|
<pre>
|
|
// PathError records an error and the operation and
|
|
// file path that caused it.
|
|
type PathError struct {
|
|
Op string; // "open", "unlink", etc.
|
|
Path string; // The associated file.
|
|
Error Error; // Returned by the system call.
|
|
}
|
|
|
|
func (e *PathError) String() string {
|
|
return e.Op + " " + e.Path + ": " + e.Error.String();
|
|
}
|
|
</pre>
|
|
<p>
|
|
<code>PathError</code>'s <code>String</code> generates
|
|
a string like this:
|
|
</p>
|
|
<pre>
|
|
open /etc/passwx: no such file or directory
|
|
</pre>
|
|
<p>
|
|
Such an error, which includes the problematic file name, the
|
|
operation, and the operating system error it triggered, is useful even
|
|
if printed far from the call that caused it;
|
|
it is much more informative than the plain
|
|
"no such file or directory".
|
|
</p>
|
|
|
|
<p>
|
|
Callers that care about the precise error details can
|
|
use a type switch or a type assertion to look for specific
|
|
errors and extract details. For <code>PathErrors</code>
|
|
this might include examining the internal <code>Error</code>
|
|
field for recoverable failures.
|
|
</p>
|
|
|
|
<pre>
|
|
for try := 0; try < 2; try++ {
|
|
file, err := os.Open(filename, os.O_RDONLY, 0);
|
|
if err == nil {
|
|
return
|
|
}
|
|
if e, ok := err.(*os.PathError); ok && e.Error == os.ENOSPC {
|
|
deleteTempFiles(); // Recover some space.
|
|
continue
|
|
}
|
|
return
|
|
}
|
|
</pre>
|
|
|
|
<h2>More to come</h2>
|
|
|
|
<!---
|
|
|
|
<h2 id="idioms">Idioms</h2>
|
|
|
|
|
|
<h3 id="buffer-slice">Use parallel assignment to slice a buffer</h3>
|
|
|
|
<pre>
|
|
header, body, checksum := buf[0:20], buf[20:n-4], buf[n-4:n];
|
|
</pre>
|
|
|
|
<h2>Data-Driven Programming</h2>
|
|
|
|
<p>
|
|
tables
|
|
</p>
|
|
|
|
<p>
|
|
XXX struct tags for marshaling.
|
|
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>
|
|
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
|
|
no more tests were run.
|
|
XXX
|
|
test bottom up
|
|
test runs top to bottom
|
|
how to use gotest
|
|
XXX
|
|
</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.
|
|
<font color="red">((link to go code search for 'for.*range' here))</font>
|
|
</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>
|
|
|
|
<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 idiosyncrasies 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 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>
|
|
|
|
<pre>
|
|
TODO
|
|
verifying implementation
|
|
type Color uint32
|
|
|
|
// Check that Color implements image.Color and image.Image
|
|
var _ image.Color = Black
|
|
var _ image.Image = Black
|
|
</pre>
|
|
-->
|