From 401c0b3b46a286e698da948129fae64fd9de0523 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Thu, 13 Aug 2009 11:29:05 -0700 Subject: [PATCH] get this out of the way OCL=33178 CL=33180 --- doc/effective_go.html | 179 ++++++++++++++++++++++-------------------- 1 file changed, 96 insertions(+), 83 deletions(-) diff --git a/doc/effective_go.html b/doc/effective_go.html index 5eec23fdfd3..fc777c09515 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -27,80 +27,6 @@ only as the core library but also as examples of how to use the language. Read them and follow their example.

-

Be consistent

- -

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

- -

-Consider for loops. -Traditionally, a loop over n -elements begins: -

- -
-for i := 0; i < n; i++ {
-
- -

-Much of the time, the loop could run in the opposite order -and still be correct: -

- -
-for i := n-1; i >= 0; i-- {
-
- -

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

- -

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

Formatting

@@ -403,18 +329,19 @@ or n and cnt.

Idioms

-TODO: Add links to code once godoc can handle it. - -

Address literals to allocate and initialize

+

Allocate using literals

-Taking the address of a struct or array literal evaluates to a -new instance each time it is evaluated. -Use these expressions to avoid the repetition of filling +A struct literal is an expression that creates a +new instance each time it is evaluated. The address of such +an expression therefore points to a fresh instance each time. +Use such expressions to avoid the repetition of filling out a data structure. 

+length := Point{x, y}.Abs();
+
 // Prepare RPCMessage to send to server
 rpc := &RPCMessage {
 	Version: 1,
@@ -427,6 +354,11 @@ rpc := &RPCMessage {
 };
+

+Array, slice, and map literals behave similarly, although it is +unusual to need the address of a slice or map. +

+

Use parallel assignment to slice a buffer

@@ -586,17 +518,20 @@ type PathError struct {
 }
 
 func (e *PathError) String() string {
-	return e.Op + " " + e.Path + ": " + e.Error.String();
+	return e.Op + " " + e.Path + ": " + e.Error.String();
 }
+

PathError's String formats the error nicely, including the operation and file name tha failed; just printing the error generates a message, such as +

 open /etc/passwx: no such file or directory
+

that is useful even if printed far from the call that triggered it.

@@ -604,7 +539,10 @@ triggered it.

Callers that care about the precise error details can use a type switch or a type guard to look for specific -errors and extract details. +errors and extract details. For PathErrors +this might include examining the internal Error +to see if it is os.EPERM or os.ENOENT, +for instance.

Programmer-defined types

@@ -615,7 +553,7 @@ errors and extract details. The constructor for the type pkg.MyType should be named pkg.NewMyType and should return *pkg.MyType. The implementation of NewTypeName often uses the -struct allocation idiom. +struct allocation idiom.

go/src/pkg/os/file.go: @@ -784,6 +722,81 @@ makes it easy to check that the return value is exactly as expected.

+

Be consistent

+ +

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

+ +

+Consider for loops. +Traditionally, a loop over n +elements begins: +

+ +
+for i := 0; i < n; i++ {
+
+ +

+Much of the time, the loop could run in the opposite order +and still be correct: +

+ +
+for i := n-1; i >= 0; i-- {
+
+ +

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

+ +

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

+