From: Russ Cox Date: Sun, 8 Nov 2009 09:07:53 +0000 (-0800) Subject: effective go: tiny fixes X-Git-Tag: weekly.2009-11-10~54 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=24ce19c71db93ad4cf425a3a3b0f67fe3de8c803;p=gostls13.git effective go: tiny fixes one real bug: *[]float -> *[3]float R=r http://go/go-review/1024016 --- diff --git a/doc/effective_go.html b/doc/effective_go.html index 103cc82495..ac012397a6 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -6,7 +6,7 @@ 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. +different in character from programs written 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. @@ -37,7 +37,7 @@ 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 +might be implemented, they can provide answers, ideas and background.

@@ -83,7 +83,7 @@ type T struct {

-gofmt will make the columns line up. +gofmt will line up the columns: 

@@ -237,7 +237,7 @@ var (
 
 

 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.
+such as the fact that a set of variables is protected by a mutex.
 

 
 
@@ -293,14 +293,14 @@ defines which version is being used.
 Another convention is that the package name is the base name of
 its source directory;
 the package in src/pkg/container/vector
-is installed as "container/vector" but has name vector,
+is imported as "container/vector" but has name vector,
 not container_vector and not containerVector.
 

 
 

 The importer of a package will use the name to refer to its contents
 (the import . notation is intended mostly for tests and other
-unusual situations) and exported names in the package can use that fact
+unusual situations), so exported names in the package can use that fact
 to avoid stutter.
 For instance, the buffered reader type in the bufio package is called Reader,
 not BufReader, because users see it as bufio.Reader,
@@ -308,9 +308,9 @@ which is a clear, concise name.
 Moreover,
 because imported entities are always addressed with their package name, bufio.Reader
 does not conflict with io.Reader.
-Similarly, the function to make new instances of vector.Vector
-—which is the definition of a constructor in Go—would
-normally be called NewVector but since
+Similarly, the function to make new instances of vector.Vector—which
+is the definition of a constructor in Go—would
+normally be called NewVector, but since
 Vector is the only type exported by the package, and since the
 package is called vector, it's called just New.
 Clients of the package see that as vector.New.
@@ -664,11 +664,11 @@ and modifying an argument.
 

 
 

-In C, a write error is signaled by a negative byte count with the
+In C, a write error is signaled by a negative count with the
 error code secreted away in a volatile location.
 In Go, Write
-can return a byte count and an error: "Yes, you wrote some
-bytes but not all of them because you filled the device".
+can return a count and an error: “Yes, you wrote some
+bytes but not all of them because you filled the device”.
 The signature of *File.Write in package os is:
 

 
@@ -765,7 +765,7 @@ They do different things and apply to different types, which can be confusing,
 but the rules are simple.
 Let's talk about new() 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
+in other languages: new(T) allocates zeroed storage for a new item of type
 T and returns its address, a value of type *T.
 In Go terminology, it returns a pointer to a newly allocated zero value of type
 T.
@@ -873,18 +873,13 @@ order, with the missing ones left as their respective zero values.  Thus we coul
 
 

 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.
+a zero value for the type.  The expressions new(File) and &File{} are equivalent.
 

 
-
-new(File)
-&File{}
-

-
 

 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 EnoError,
+In these examples, the initializations work regardless of the values of Enone,
 Eio, and Einval, as long as they are distinct.
 

 
@@ -945,7 +940,8 @@ v := make([]int, 100);
 

 
 

-Remember that make() applies only to maps, slices and channels.
+Remember that make() applies only to maps, slices and channels
+and does not return a pointer.
 To obtain an explicit pointer allocate with new().
 

 
@@ -953,7 +949,7 @@ To obtain an explicit pointer allocate with new().
 
 

 Arrays are useful when planning the detailed layout of memory and sometimes
-can help avoid allocation but primarily
+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.
 

@@ -981,7 +977,7 @@ you can pass a pointer to the array.
 

 
 
-func Sum(a *[]float) (sum float) {
+func Sum(a *[3]float) (sum float) {
 	for _, v := range a {
 		sum += v
 	}
@@ -1010,8 +1006,8 @@ 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 Read
-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
+function can therefore accept a slice argument rather than a pointer
+and a count; the length within the slice sets an upper
 limit of how much data to read.  Here is the signature of the
 Read method of the File type in package
 os:
@@ -1085,10 +1081,11 @@ structure holding the pointer, length, and capacity) is passed by value.
 

 Maps are a convenient and powerful built-in data structure to associate
 values of different types.
-The key can be of any type that implements equality, such as integers,
+The key can be of any type for which the equality operator is defined,
+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 for them.
+supports equality).  Structs, arrays and slices cannot be used as map keys,
+because equality is not defined on those types.
 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.
@@ -1514,7 +1511,7 @@ A type can implement multiple interfaces.
 For instance, a collection can be sorted
 by the routines in package sort if it implements
 sort.Interface, which contains Len(),
-Less(i, j int), and Swap(i, j int),
+Less(i, j int) bool, and Swap(i, j int),
 and it could also have a custom formatter.
 In this contrived example Sequence satisfies both.
 

@@ -1654,7 +1651,7 @@ implementation of the Cipher interface and any
 io.Reader.  Because they return io.Reader
 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
+calls must be edited, but because the surrounding code must treat the result only
 as an io.Reader, it won't notice the difference.
 

 
@@ -2247,16 +2244,16 @@ Once the message buffer is ready, it's sent to the server on
 serverChan.
 

 
-var freelist = make(chan *Buffer, 100)
-var server_chan = make(chan *Buffer)
+var freeList = make(chan *Buffer, 100)
+var serverChan = make(chan *Buffer)
 
 func client() {
 	for {
-		b, ok := <-freeList;  // grab one if available
-		if !ok {              // free list empty; allocate a new buffer
+		b, ok := <-freeList;  // grab a buffer if available
+		if !ok {              // if not, allocate a new one
 			b = new(Buffer)
 		}
-		load(b);              // grab the next message, perhaps from the net
+		load(b);              // read next message from the net
 		serverChan <- b;      // send to server
 	}
 }
@@ -2393,7 +2390,7 @@ import (
 	"template";
 )
 
-var addr = flag.String("addr", ":1718", "http service address") // Q = 17, R = 18
+var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18
 var fmap = template.FormatterMap{
 	"html": template.HtmlFormatter,
 	"url+html": UrlHtmlFormatter,
@@ -2456,7 +2453,7 @@ server; it blocks while the server runs.
 

 

 QR just receives the request, which contains form data, and
-executes the template on the data in the field named s.
+executes the template on the data in the form value named s.
 

 

 The template package, inspired by templ.Execute, in this case the
-string in the form data.  
+form value.  
 Within the template text (templateStr),
 brace-delimited pieces denote template actions.
 The piece from the {.section @}
 to {.end} executes with the value of the data item @,
-which is a shorthand for “the current item”, in this case the form data.
+which is a shorthand for “the current item”, which is the form value.
 (When the string is empty, this piece of the template is suppressed.)