From d1a3b98a8da322622e033cf573b47a3d804fc1ff Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Fri, 31 Jul 2009 11:41:30 -0700 Subject: [PATCH] cleanup pass before big edits R=rsc DELTA=73 (27 added, 25 deleted, 21 changed) OCL=32587 CL=32587 --- doc/effective_go.html | 94 ++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 46 deletions(-) diff --git a/doc/effective_go.html b/doc/effective_go.html index 2d963fd83b..222284069d 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -3,7 +3,7 @@

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.

Read good code

-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.

Be consistent

-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.

Formatting

@@ -103,21 +100,26 @@ you wrote or edited based on style alone. Formatting issues are the most contentious but the least consequential. People adapt to different formatting styles, -even if at first the styles “look weird,” but they shouldn't be asked to. Everyone should use the same formatting; as in English, consistent punctuation and spacing make the text easier to read. Most of the local formatting style can be -picked up by reading existing Go programs (see above), +picked up by reading existing Go programs, but to make them explicit here are some common points.

Use tabs

-The local style is to use tabs, not spaces, for indentation. +Use tabs, not spaces, for indentation. +

+ +

Don't worry about columnation

+ +

+Let tools such as gofmt take care of lining things up.

Trim trailing white space

@@ -126,12 +128,12 @@ The local style is to use tabs, not spaces, for indentation. There should be no trailing white space at the end of lines.

-

Don't wrap lines mechanically

+

Don't wrap lines

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.

Omit parentheses in control structures

@@ -187,7 +189,7 @@ func Quote(s string) string {

-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)];

Omit needless else bodies

-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.

@@ -434,6 +436,16 @@ There is no need to pass a pointer to a return value.

Errors

+

Return 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. +

+

Handle errors first

@@ -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);
-

Return 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. -

-

Return structured errors

Implementations of os.Errors should -- 2.48.1