code review 4852041: FAQ: lots of small tweaks plus a couple of new discussions.

doc/go_faq.html

 <!-- FAQ -->
 
 <h2 id="Origins">Origins</h2>
 
 <h3 id="What_is_the_purpose_of_the_project">
 What is the purpose of the project?</h3>
 
 <p>
 No major systems language has emerged in over a decade, but over that time
 the computing landscape has changed tremendously. There are several trends:
+</p>
 
 <ul>
 <li>
 Computers are enormously quicker but software development is not faster.
 <li>
 Dependency management is a big part of software development today but the
 &ldquo;header files&rdquo; of languages in the C tradition are antithetical to clean
 dependency analysis&mdash;and fast compilation.
 <li>
 There is a growing rebellion against cumbersome type systems like those of
 Java and C++, pushing people towards dynamically typed languages such as
 Python and JavaScript.
 <li>
 Some fundamental concepts such as garbage collection and parallel computation
 are not well supported by popular systems languages.
 <li>
 The emergence of multicore computers has generated worry and confusion.
 </ul>
-</p>
 
 <p>
 We believe it's worth trying again with a new language, a concurrent,
 garbage-collected language with fast compilation. Regarding the points above:
+</p>
 
 <ul>
 <li>
 It is possible to compile a large Go program in a few seconds on a single computer.
 <li>
 Go provides a model for software construction that makes dependency
 analysis easy and avoids much of the overhead of C-style include files and
 libraries.
 <li>
 Go's type system has no hierarchy, so no time is spent defining the
 relationships between types. Also, although Go has static types the language
 attempts to make types feel lighter weight than in typical OO languages.
 <li>
 Go is fully garbage-collected and provides fundamental support for
 concurrent execution and communication.
 <li>
 By its design, Go proposes an approach for the construction of system
 software on multicore machines.
 </ul>
-</p>
 
 <h3 id="What_is_the_origin_of_the_name">
 What is the origin of the name?</h3>
 
 <p>
 &ldquo;Ogle&rdquo; would be a good name for a Go debugger.
 </p>
 
 <h3 id="Whats_the_origin_of_the_mascot">
 What's the origin of the mascot?</h3>
@@ skipping 34 matching lines @@
 parallel with unrelated work.  By January 2008, Ken had started work
 on a compiler with which to explore ideas; it generated C code as its
 output.  By mid-year the language had become a full-time project and
 had settled enough to attempt a production compiler.  In May 2008,
 Ian Taylor independently started on a GCC front end for Go using the
 draft specification.  Russ Cox joined in late 2008 and helped move the language
 and libraries from prototype to reality.
 </p>
 
 <p>
-Many others have contributed ideas, discussions, and code.
+Go became a public open source project on November 10, 2009.
+Many people from the community have contributed ideas, discussions, and code.
 </p>
 
 <h3 id="creating_a_new_language">
 Why are you creating a new language?</h3>
 <p>
 Go was born out of frustration with existing languages and
 environments for systems programming.  Programming had become too
 difficult and the choice of languages was partly to blame.  One had to
 choose either efficient compilation, efficient execution, or ease of
 programming; all three were not available in the same mainstream
@@ skipping 188 matching lines @@
 Why does Go not have exceptions?</h3>
 <p>
 We believe that coupling exceptions to a control
 structure, as in the <code>try-catch-finally</code> idiom, results in
 convoluted code.  It also tends to encourage programmers to label
 too many ordinary errors, such as failing to open a file, as
 exceptional.
 </p>
 
 <p>
-Go takes a different approach.  Instead of exceptions, it has a couple
+Go takes a different approach.  For plain error handling, Go's multi-value
+returns make it easy to report an error without overloading the return value.
+<a href="http://blog.golang.org/2011/07/error-handling-and-go.html">A
+canonical error type, coupled
+with Go's other features</a>, makes error
+handling pleasant but quite different from that in other languages.
+</p>
+
+<p>
+Go also has a couple
 of built-in functions to signal and recover from truly exceptional
 conditions.  The recovery mechanism is executed only as part of a
 function's state being torn down after an error, which is sufficient
 to handle catastrophe but requires no extra control structures and,
 when used well, can result in clean error-handling code.
 </p>
 
 <p>
 See the <a href="http://blog.golang.org/2010/08/defer-panic-and-recover.html">Defer, Panic, and Recover</a> article for details.
 </p>
@@ skipping 37 matching lines @@
 the Go language and libraries that differ from modern practices, simply
 because we feel it's sometimes worth trying a different approach.
 </p>
 
 <h3 id="csp">
 Why build concurrency on the ideas of CSP?</h3>
 <p>
 Concurrency and multi-threaded programming have a reputation
 for difficulty.  We believe the problem is due partly to complex
 designs such as pthreads and partly to overemphasis on low-level details
-such as mutexes, condition variables, and even memory barriers.
+such as mutexes, condition variables, and memory barriers.
 Higher-level interfaces enable much simpler code, even if there are still
 mutexes and such under the covers.
 </p>
 
 <p>
 One of the most successful models for providing high-level linguistic support
 for concurrency comes from Hoare's Communicating Sequential Processes, or CSP.
 Occam and Erlang are two well known languages that stem from CSP.
 Go's concurrency primitives derive from a different part of the family tree
 whose main contribution is the powerful notion of channels as first class objects.
 </p>
 
 <h3 id="goroutines">
 Why goroutines instead of threads?</h3>
 <p>
 Goroutines are part of making concurrency easy to use.  The idea, which has
 been around for a while, is to multiplex independently executing
-functions&mdash;coroutines, really&mdash;onto a set of threads.
+functions&mdash;coroutines&mdash;onto a set of threads.
 When a coroutine blocks, such as by calling a blocking system call,
 the run-time automatically moves other coroutines on the same operating
 system thread to a different, runnable thread so they won't be blocked.
 The programmer sees none of this, which is the point.
 The result, which we call goroutines, can be very cheap: unless they spend a lot of time
 in long-running system calls, they cost little more than the memory
-for the stack.
+for the stack, which is just a few kilobytes.
 </p>
 
 <p>
 To make the stacks small, Go's run-time uses segmented stacks.  A newly
 minted goroutine is given a few kilobytes, which is almost always enough.
 When it isn't, the run-time allocates (and frees) extension segments automatically.
 The overhead averages about three cheap instructions per function call.
 It is practical to create hundreds of thousands of goroutines in the same
 address space.  If goroutines were just threads, system resources would
 run out at a much smaller number.
@@ skipping 55 matching lines @@
 different approach.
 </p>
 
 <p>
 Rather than requiring the programmer to declare ahead of time that two
 types are related, in Go a type automatically satisfies any interface
 that specifies a subset of its methods.  Besides reducing the
 bookkeeping, this approach has real advantages.  Types can satisfy
 many interfaces at once, without the complexities of traditional
 multiple inheritance.
-Interfaces can be very lightweight&mdash;having one or even zero methods
-in an interface can express useful concepts.
+Interfaces can be very lightweight&mdash;an interface with
+one or even zero methods can express a useful concept.
 Interfaces can be added after the fact if a new idea comes along
 or for testing&mdash;without annotating the original types.
 Because there are no explicit relationships between types
 and interfaces, there is no type hierarchy to manage or discuss.
 </p>
 
 <p>
 It's possible to use these ideas to construct something analogous to
 type-safe Unix pipes.  For instance, see how <code>fmt.Fprintf</code>
 enables formatted printing to any output, not just a file, or how the
 <code>bufio</code> package can be completely separate from file I/O,
 or how the <code>crypto</code> packages stitch together block and
 stream ciphers.  All these ideas stem from a single interface
 (<code>io.Writer</code>) representing a single method
 (<code>Write</code>).  And that's only scratching the surface.
 </p>
 
 <p>
 It takes some getting used to but this implicit style of type
-dependency is one of the most exciting things about Go.
+dependency is one of the most productive things about Go.
 </p>
 
 <h3 id="methods_on_basics">
 Why is <code>len</code> a function and not a method?</h3>
 <p>
 We debated this issue but decided
 implementing <code>len</code> and friends as functions was fine in practice and
 didn't complicate questions about the interface (in the Go type sense)
 of basic types.
 </p>
@@ skipping 73 matching lines @@
 func (b Bar) ImplementsFooer() {}
 func (b Bar) Foo() {}
 </pre>
 
 <p>
 Most code doesn't make use of such constraints, since they limit the utility of·
 the interface idea. Sometimes, though, they're necessary to resolve ambiguities
 among similar interfaces.
 </p>
 
+<h3 id="t_and_equal_interface">
+Why doesn't type T satisfy the Equal interface?</h3>
+
+<p>
+Consider this simple interface to represent an object that can compare
+itself with another value:
+</p>
+
+<pre>
+type Equaler interface {
+        Equal(Equaler) bool
+}
+</pre>
+
+<p>
+and this type, <code>T</code>:
+</p>
+
+<pre>
+type T int
+func (t T) Equal(u T) bool { return t == u } // does not satisfy Equaler
+</pre>
+
+<p>
+Unlike the analogous situation in some object-oriented type systems,

[rsc, 2011/08/05 21:35:34]

s/the/an/
s/object-oriented/polymorphic/

+<code>T</code> does not implement <code>Equaler</code>.
+The argument type of <code>T.Equal</code> is <code>T</code>,
+not literally the required type <code>Equaler</code>.
+</p>
+
+<p>
+In Go, the type system does not promote the argument of
+<code>Equal</code>; that is the programmer's responsibility, as
+illustrated by the type <code>T2</code>, which does implement
+<code>Equaler</code>:
+</p>
+
+<pre>
+type T2 int
+func (t T2) Equal(u Equaler) bool { return t == u.(T2) }  // satisfies Equaler
+</pre>
+
+<p>
+Even this isn't like other type systems, though, because in Go <em>any</em>
+type that satisfies <code>Equaler</code> could be passed as the
+argument to <code>T2.Equal</code>, and at run time we must
+check that the argument is of type <code>T2</code>.
+Some languages arrange to make that guarantee at compile time.
+</p>
+
+<p>
+A related example goes the other way:
+</p>
+
+<pre>
+type Opener interface {
+   Open(name) Reader
+}
+
+func (t T3) Open() *os.File
+</pre>
+
+<p>
+In Go, <code>T3</code> does not satisfy <code>Opener</code>,
+although it might in another language.
+</p>
+
+<p>
+While it is true that Go's type system does less for the programmer
+in such cases, the lack of subtype inheritance makes the rules about

[rsc, 2011/08/05 21:35:34]

s/subtype inheritance/subtyping/

+interface satisfaction very easy to state: are the function's names
+and signatures exactly those of the interface?
+Go's rule is also easy to implement efficiently.
+We feel these benefits offset the lack of
+automatic type promotion. Should Go one day adopt some form of generic
+typing, we expect there would be a way to express the idea of these
+examples and also have them be statically checked.
+</p>
+
 <h3 id="convert_slice_of_interface">
 Can I convert a []T to an []interface{}?</h3>
 
 <p>
 Not directly because they do not have the same representation in memory.
 It is necessary to copy the elements individually to the destination
 slice. This example converts a slice of <code>int</code> to a slice of
 <code>interface{}</code>:
 </p>
 
@@ skipping 128 matching lines @@
 makes a copy of the thing stored in the interface value.  If the interface
 value holds a struct, copying the interface value makes a copy of the
 struct.  If the interface value holds a pointer, copying the interface value
 makes a copy of the pointer, but again not the data it points to.·
 </p>
 
 <h3 id="methods_on_values_or_pointers">
 Should I define methods on values or pointers?</h3>
 
 <pre>
-func (s *MyStruct) someMethod() { } // method on pointer
-func (s MyStruct) someMethod() { }  // method on value
+func (s *MyStruct) pointerMethod() { } // method on pointer
+func (s MyStruct)  valueMethod()   { } // method on value
 </pre>
 
 <p>
+For programmers unaccustomed to pointers, the distinction between these
+two examples can be confusing, but the situation is actually very simple.
 When defining a method on a type, the receiver (<code>s</code> in the above
-example) behaves exactly is if it were an argument to the method. Define the
-method on a pointer type if you need the method to modify the data the receiver
-points to. Otherwise, it is often cleaner to define the method on a value type.
+example) behaves exactly as if it were an argument to the method.
+Whether to define the receiver as a value or as a pointer is the same
+question, then, as whether a function argument should be a value or
+a pointer.
+There are several considerations.
 </p>
 
+<p>
+First, and most important, does the method need to modify the
+receiver?
+If it does, the receiver <em>must</em> be a pointer.
+(Slices and maps are reference types, so their story is a little
+more subtle, but for instance to change the length of a slice
+in a method the receiver must still be a pointer.)
+In the examples
+above, if <code>pointerMethod</code> modifies the fields of <code>s</code>,
+the caller will see those changes, but <code>valueMethod</code> is called
+with a copy of the caller's argument (that's the definition of passing a value),
+so changes it makes will be invisible to the caller.
+(By the way, pointer receivers are identical to the situation in Java, although
+in Java the pointers are hidden under the covers; it's Go's value receivers that
+are unusual.)
+</p>
+
+<p>
+Second is the consideration of efficiency. If the receiver is large, a big <code>struct</code>
+for instance, it will be much cheaper to use a pointer receiver.
+</p>
+
+<p>
+Next is consistency. If some of the methods of the type must have
+pointer receivers, the rest should too, so the method set is
+consistent regardless of how the type is used.
+See the section on <a href="#different_method_sets">method sets</a> for details.
+</p>
+
+<p>
+For other types, such as basic types, slices, and small <code>structs</code>,
+a value receiver is very cheap so unless
+the semantics of the method requires a pointer, a value receiver is efficient and clear.
+</p>
+
+
 <h3 id="new_and_make">
 What's the difference between new and make?</h3>
 
 <p>
 In short: <code>new</code> allocates memory, <code>make</code> initializes
 the slice, map, and channel types.
 </p>
 
 <p>
 See the <a href="/doc/effective_go.html#allocation_new">relevant section
@@ skipping 344 matching lines @@
 indicate.
 </p>
 
 <p>
 Still, there is room for improvement. The compilers are good but could be
 better, many libraries need major performance work, and the garbage collector
 isn't fast enough yet (even if it were, taking care not to generate unnecessary·
 garbage can have a huge effect).
 </p>
 
+<p>
+In any case, Go can often be very competitive. See the blog post about
+<a href="http://blog.golang.org/2011/06/profiling-go-programs.html">profiling
+Go programs</a> for an informative example.
+
 <h2 id="change_from_c">Changes from C</h2>
 
 <h3 id="different_syntax">
 Why is the syntax so different from C?</h3>
 <p>
 Other than declaration syntax, the differences are not major and stem
 from two desires.  First, the syntax should feel light, without too
 many mandatory keywords, repetition, or arcana.  Second, the language
 has been designed to be easy to analyze
 and can be parsed without a symbol table.  This makes it much easier
@@ skipping 34 matching lines @@
 <pre>
         a := uint64(1);
 </pre>
 <p>
 Parsing is also simplified by having a distinct grammar for types that
 is not just the expression grammar; keywords such as <code>func</code>
 and <code>chan</code> keep things clear.
 </p>
 
 <p>
-See the <a href="http://blog.golang.org/2010/07/gos-declaration-syntax.html">Go's Declaration Syntax</a> article for more details.
+See the article about
+<a href="http://blog.golang.org/2010/07/gos-declaration-syntax.html">Go's Declaration Syntax</a>
+for more details.
 </p>
 
 <h3 id="no_pointer_arithmetic">
 Why is there no pointer arithmetic?</h3>
 <p>
 Safety.  Without pointer arithmetic it's possible to create a
 language that can never derive an illegal address that succeeds
 incorrectly.  Compiler and hardware technology have advanced to the
 point where a loop using array indices can be as efficient as a loop
 using pointer arithmetic.  Also, the lack of pointer arithmetic can
@@ skipping 66 matching lines @@
 Automatic garbage collection makes concurrent code far easier to write.
 Of course, implementing garbage collection in a concurrent environment is
 itself a challenge, but meeting it once rather than in every
 program helps everyone.
 </p>
 
 <p>
 Finally, concurrency aside, garbage collection makes interfaces
 simpler because they don't need to specify how memory is managed across them.
 </p>
+
+<p>
+On the topic of performance, keep in mind that Go gives the programmer
+considerable control over memory layout and allocation, much more than
+is typical in garbage-collected languages. A careful programmer can reduce
+the garbage collection overhead dramatically by using the language well;
+see the article about
+<a href="http://blog.golang.org/2011/06/profiling-go-programs.html">profiling
+Go programs</a> for a worked example, including a demonstration of Go's
+profiling tools.
+</p>