This document gives tips for writing clear, idiomatic Go code -and points out common mistakes to avoid. +and points out common mistakes. It augments the language specification and the tutorial, both of which you should read first. @@ -12,7 +12,7 @@ should read first.
-The first step towards learning to write good code is to read good code. +The first step in learning to write good code is to read good code. The Go package sources are intended to serve not only as the core library but also as examples of how to @@ -22,9 +22,18 @@ use the language. Read them and follow their example.
-Consistency makes programs easy to read. -If a program says the same thing twice, -it should say it the same way both times. +Programmers often want their style to be distinctive, +writing loops backwards or using custom spacing and +naming conventions. Such idiosyncracies come at a +price, however: by making the code look different, +they make it harder to understand. +Consistency trumps personal +expression in programming. +
+ ++If a program does the same thing twice, +it should do it the same way both times. Conversely, if two different sections of a program look different, the reader will expect them to do different things. @@ -50,51 +59,39 @@ for i := n-1; i >= 0; i-- {
-The convention in most languages (including Go) +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. -Don't run loops backwards unless it's necessary.
Loop direction is just one
-programming decision which a programmer
-may be tempted to be distinctive:
-tabs or spaces, choice of variable names,
-choice of method names, whether a type
-has a constructor, what tests look like, and on and on.
-As in the loop example, inconsistency
-sows confusion, and wastes time.
+programming decision that must be made
+consistently; others include
+formatting, naming variables and methods,
+whether a type
+has a constructor, what tests look like, and so on.
Why is this variable called n here and cnt there?
Why is the Log constructor CreateLog when
the List constructor is NewList?
Why is this data structure initialized using
a structure literal when that one
is initialized using individual assignments?
-And so on.
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.
-Being consistent about little things
-lets readers concentrate on big ones.
-
-This document describes how to use Go effectively and idiomatically -so that a programmer seeing your code for -the first time can focus on what it does -and not why it is inconsistent with typical Go practices. -Consistency trumps every item listed below. When editing code, read the surrounding context and try to mimic it as much as possible, even if it disagrees with the rules here. It should not be possible to tell which lines you wrote or edited based on style alone. +Consistency about little things +lets readers concentrate on big ones.
-The local style is to use tabs, not spaces, for indentation. +Use tabs, not spaces, for indentation. +
+ +
+Let tools such as gofmt take care of lining things up.
Go has no 80-character limit. Don't bother with fancy line wrapping just because a line is wider than a punched card. -If you must wrap a line, indent with an extra tab. +If a line is too long, indent with an extra tab.
-The complete English sentence form admits +Use of complete English sentences admits a wider variety of automated presentations.
@@ -338,8 +340,8 @@ hdr, body, checksum := buf[0:20], buf[20:len(buf)-4], buf[len(buf)-4:len(buf)];
-If an if body doesn't flow off the end of the
-body—that is, the body ends in break, continue,
+When an if statement doesn't flow into the next statement—that is,
+the body ends in break, continue,
goto, or return—omit the else.
os.Error, not bool
+Especially in libraries, functions tend to have multiple error modes.
+Instead of returning a boolean to signal success,
+return an os.Error that describes the failure.
+Even if there is only one failure mode now,
+there may be more later.
+
@@ -446,28 +458,18 @@ so that there is no need for an explicit else.
if len(name) == 0 {
- return;
+ return os.EINVAL;
}
if IsDir(name) {
- return;
+ return os.EISDIR;
}
f, err := os.Open(name, os.O_RDONLY, 0);
if err != nil {
- return;
+ return err;
}
codeUsing(f);
-os.Error, not bool
-Few functions have just one failure mode.
-Instead of returning a boolean to signal success,
-return an os.Error that describes the failure.
-Even if there is only one failure mode now,
-there may be more later.
-
os.Errors should