slashed comments

go.html.markdown

@@ -27,9 +27,7 @@ Go comes with a great standard library and an enthusiastic community.
 // Main is a special name declaring an executable rather than a library.
 package main
 
-// An import declaration comes next.  It declares library packages referenced
+// Import declaration declares library packages referenced in this file.
-// in this file.  The list must be exactly correct!  Missing or unused packages
-// are errors, not warnings.
 import (
 	"fmt"      // A package in the Go standard library
 	"net/http" // Yes, a web server!
@@ -39,27 +37,20 @@ import (
 // A function definition.  Main is special.  It is the entry point for the
 // executable program.  Love it or hate it, Go uses brace brackets.
 func main() {
-	// Println is a function that outputs a line to stdout.  It can be
+	// Println outputs a line to stdout.
-	// called here because fmt has been imported and the function name
+	// Qualify it with the package name, fmt.
-	// "Println" is upper case.  Symbols starting with an upper case letter
-	// are publicly visible.  No other special syntax is needed to export
-	// something from a package.
-	// To call Println, qualify it with the package name, fmt.
 	fmt.Println("Hello world!")
 
 	// Call another function within this package.
 	beyondHello()
 }
 
-// Idiomatic Go uses camel case.  Functions have parameters in parentheses.
+// Functions have parameters in parentheses.
 // If there are no parameters, empty parens are still required.
 func beyondHello() {
 	var x int // Variable declaration.  Variables must be declared before use.
 	x = 3     // Variable assignment.
-	// "Short" declarations use := syntax to declare and assign, infering the
+	// "Short" declarations use := to infer the type, declare, and assign.
-	// type from the right hand side as much as possible and using some
-	// defaults where the rhs could be interpreted different ways.
-	// Idiomatic Go uses short declarations in preference to var keyword.
 	y := 4
 	sum, prod := learnMultiple(x, y)        // function returns two values
 	fmt.Println("sum:", sum, "prod:", prod) // simple output
@@ -67,8 +58,6 @@ func beyondHello() {
 }
 
 // Functions can have parameters and (multiple!) return values.
-// In declarations, the symbol precedes the type, and the type does not have
-// to be repeated if it is the same for multiple symbols in a row.
 func learnMultiple(x, y int) (sum, prod int) {
 	return x + y, x * y // return two values
 }
@@ -87,12 +76,11 @@ can include line breaks.` // same string type
 	f := 3.14195 // float64, an IEEE-754 64-bit floating point number
 	c := 3 + 4i  // complex128, represented internally with two float64s
 
-	// You can use var syntax with an initializer if you want
+	// Var syntax with an initializers.
-	// something other than the default that a short declaration gives you.
 	var u uint = 7 // unsigned, but implementation dependent size as with int
 	var pi float32 = 22. / 7
 
-	// Or more idiomatically, use conversion syntax with a short declaration.
+	// Conversion syntax with a short declaration.
 	n := byte('\n') // byte is an alias for uint8
 
 	// Arrays have size fixed at compile time.
@@ -106,12 +94,8 @@ can include line breaks.` // same string type
 	var d2 [][]float64      // declaration only, nothing allocated here
 	bs := []byte("a slice") // type conversion syntax
 
-	p, q := learnMemory() // A little side bar.
+	p, q := learnMemory() // declares p, q to be type pointer to int.
-	// Did you read it?  This short declaration declares p and q to be of
+	fmt.Println(*p, *q)   // * follows a pointer.  This prints two ints.
-	// type pointer to int.  P is now pointing into a block of of 20 ints, but
-	// the only one accessible is the one that p is pointing at.  There is
-	// no p++ to get at the next one.
-	fmt.Println(*p, *q) // * follows a pointer.  This prints two ints.
 
 	// Maps are a dynamically growable associative array type, like the
 	// hash or dictionary types of some other languages.
@@ -130,26 +114,13 @@ can include line breaks.` // same string type
 // Go is fully garbage collected.  It has pointers but no pointer arithmetic.
 // You can make a mistake with a nil pointer, but not by incrementing a pointer.
 func learnMemory() (p, q *int) {
-	// Named return values p and q have type pointer to int.  They are
+	// Named return values p and q have type pointer to int.
-	// initialized to nil at this point.  Evaluating *p or *q here would cause
-	// a panic--a run time error.
 	p = new(int) // built-in function new allocates memory.
 	// The allocated int is initialized to 0, p is no longer nil.
 	s := make([]int, 20) // allocate 20 ints as a single block of memory
 	s[3] = 7             // assign one of them
 	r := -2              // declare another local variable
-	return &s[3], &r     // Oh my.
+	return &s[3], &r     // & takes the address of an object.
-	// The line above returns two values, yes, and both of the expressions
-	// are valid.  & takes the address of an object.  Elements of a slice are
-	// addressable, and so are local variables.  Built-in functions new and
-	// make explicitly allocate memory, but local objects can be allocated
-	// as needed.  Here memory for r will be still be referenced after the
-	// function returns so it will be allocated as well.  The int allocated
-	// with new on the other hand will no longer be referenced and can be
-	// garbage collected as needed by the Go runtime.  The memory allocated
-	// with make will still be referenced at that one element, and so it
-	// cannot be garbage collected.  All 20 ints remain in memory because
-	// one of them is still referenced.
 }
 
 func expensiveComputation() int {
@@ -161,16 +132,13 @@ func learnFlowControl() {
 	if true {
 		fmt.Println("told ya")
 	}
-	// This is how we format the brace brackets.  Formatting is standardized
+	// Formatting is standardized by the command line command "go fmt."
-	// by the command line command "go fmt."  Everybody does it.  You will
-	// suffer endless disparaging remarks until you conform as well.
 	if false {
 		// pout
 	} else {
 		// gloat
 	}
-	// If statements can be chained of course, but it's idiomatic to use
+	// Use switch in preference to chained if statements.
-	// the handy switch statement instead.
 	x := 1
 	switch x {
 	case 0:
@@ -179,10 +147,7 @@ func learnFlowControl() {
 	case 2:
 		// unreached
 	}
-	// Like if, for doesn't use parens either.  The scope of a variable
+	// Like if, for doesn't use parens either.
-	// declared in the first clause of the for statement is the statement
-	// and block.  This x shadows the x declared above, but goes out of
-	// scope after the for block.
 	for x := 0; x < 3; x++ { // ++ is a statement
 		fmt.Println("iteration", x)
 	}
@@ -193,14 +158,11 @@ func learnFlowControl() {
 		break    // just kidding
 		continue // unreached
 	}
-	// The initial assignment of the for statement is handy enough that Go
+	// As with for, := in an if statement means to declare and assign y first,
-	// if statements can have one as well.  Just like in the for statement,
+	// then test y > x.
-	// the := here means to declare and assign y first, then test y > x.
-	// The scope of y is limited to the if statement and block.
 	if y := expensiveComputation(); y > x {
 		x = y
 	}
-	// Functions are first class objects and function literals are handy.
 	// Function literals are closures.
 	xBig := func() bool {
 		return x > 100 // references x declared above switch statement.
@@ -209,48 +171,25 @@ func learnFlowControl() {
 	x /= 1e5                     // this makes it == 10
 	fmt.Println("xBig:", xBig()) // false now
 
-	// When you need it, you'll love it.  Actually Go's goto has been reformed
+	// When you need it, you'll love it.
-	// a bit to avoid indeterminate states.  You can't jump around variable
-	// declarations and you can't jump into blocks.
 	goto love
 love:
 
 	learnInterfaces() // Good stuff coming up!
 }
 
-// An interface is a list of functionality that a type supports.  Notably
+// Define Stringer as an interface type with one method, String.
-// missing from an interface definition is any declaration of which types
-// implement the interface.  Types simply implement an interface or they don't.
-//
-// An interface can have any number of methods, but it's actually common
-// for an interface to have only single method.  It is idiomatic in this
-// case for the single method to be named with some action, and for the
-// interface name to end in "er."
-//
-// An interface definition is one kind of a type definition.  Interface is
-// a built in type.  Stringer is defined here as an interface type with one
-// method, String.
 type Stringer interface {
 	String() string
 }
 
-// Struct is another built in type.  A struct aggregates "fields."
+// Define pair as a struct with two fields, ints named x and y.
-// Pair here has two fields, ints named x and y.
 type pair struct {
 	x, y int
 }
 
-// User defined types can have "methods." These are functions that operate
+// Define a method on type pair.  Pair now implements Stringer.
-// in the context of an instance of the user defined type.  The instance
+func (p pair) String() string { // p is called the "receiver"
-// is called the "receiver" and is identified with a declaration just in front
-// of the method name.  The receiver here is "p." In most ways the receiver
-// works just like a function parameter.
-//
-// This String method has the same name and return value as the String method
-// of the Stringer interface.  Further, String is the only method of Stringer.
-// The pair type thus implements all methods of the Stringer interface and
-// we say simply that pair implements Stringer.  No other syntax is needed.
-func (p pair) String() string {
 	// Sprintf is another public function in package fmt.
 	// Dot syntax references fields of p.
 	return fmt.Sprintf("(%d, %d)", p.x, p.y)
@@ -261,21 +200,13 @@ func learnInterfaces() {
 	// struct.  The := syntax declares and initializes p to this struct.
 	p := pair{3, 4}
 	fmt.Println(p.String()) // call String method of p, of type pair.
-	var i Stringer          // declare i of type Stringer.
+	var i Stringer          // declare i of interface type Stringer.
 	i = p                   // valid because pair implements Stringer
 	// Call String method of i, of type Stringer.  Output same as above.
 	fmt.Println(i.String())
-	// It gets more interesting now.  We defined Stringer in this file,
+
-	// but the same interface happens to be defined in package fmt.
+	// Functions in the fmt package call the String method to ask an object
-	// Pair thus implements fmt.Stringer as well, and does so with no
+	// for a printable representation of itself.
-	// declaration of the fact.  The definition of pair doesn't mention
-	// any interfaces at all, and of course the authors of fmt.Stringer
-	// had no idea that we were going to define pair.
-	//
-	// Functions in the fmt package know how to print some standard built in
-	// types, and beyond that, they see if a type implements fmt.Stringer.
-	// If so, they simply call the String method to ask an object for a
-	// printable representation of itself.
 	fmt.Println(p) // output same as above. Println calls String method.
 	fmt.Println(i) // output same as above
 
@@ -283,57 +214,23 @@ func learnInterfaces() {
 }
 
 func learnErrorHandling() {
-	// Sometimes you just need to know if something worked or not.  Go has
+	// ", ok" idiom used to tell if something worked or not.
-	// a ", ok" idiom for that.  Something, a map expression here, but commonly
-	// a function, can return a boolean value of ok or not ok as a second
-	// return value.
 	m := map[int]string{3: "three", 4: "four"}
-	if x, ok := m[1]; !ok { // , ok is optional but see how useful it is.
+	if x, ok := m[1]; !ok { // ok will be false because 1 is not in the map.
 		fmt.Println("no one there")
 	} else {
-		fmt.Print(x)
+		fmt.Print(x) // x would be the value, if it were in the map.
 	}
 	// An error value communicates not just "ok" but more about the problem.
 	if _, err := strconv.Atoi("non-int"); err != nil { // _ discards value
 		// prints "strconv.ParseInt: parsing "non-int": invalid syntax"
 		fmt.Println(err)
 	}
-	// error is a built in type.  It is an interface with a single method,
-	// defined internally as,
-	//
-	// type error interface {
-	//     Error() string
-	// }
-	//
-	// The string returned by the Error method is conventionally a printable
-	// error message.  You can define your own error types by simply adding
-	// an Error method.  Your type then automatically implements the error
-	// interface.  We've seen two interfaces now, fmt.Stringer and error.
-
 	// We'll revisit interfaces a little later.  Meanwhile,
 	learnConcurrency()
 }
 
-// Go has concurrency support in the language definition.  The element of
+// c is a channel, a concurrency-safe communication object.
-// concurrent execution is called a "goroutine" and is similar to a thread
-// but "lighter."  Goroutines are multiplexed to operating system threads
-// and a running Go program can have far more goroutines than available OS
-// threads.  If a machine has multiple CPU cores, goroutines can run in
-// parallel.
-//
-// Go "Channels" allow communication between goroutines in a way that is
-// both powerful and easy to understand.  Channel is a type in Go and objects
-// of type channel are first class objects--they can be assigned to variables,
-// passed around to functions, and so on.  A channel works conceptually much
-// like a Unix pipe.  You put data in at one end and it comes out the other.
-// Channel "send" and "receive" operations are goroutine-safe.  No locks
-// or additional synchronization is needed.
-
-// Inc increments a number, and sends the result on a channel.  The channel
-// operation makes this function useful to run concurrently with other
-// goroutines.  There is no special declaration though that says this function
-// is concurrent.  It is an ordinary function that happens to have a
-// parameter of channel type.
 func inc(i int, c chan int) {
 	c <- i + 1 // <- is the "send" operator when a channel appears on the left.
 }
@@ -357,10 +254,9 @@ func learnConcurrency() {
 	cc := make(chan chan string)  // a channel of channels.
 	go func() { c <- 84 }()       // start a new goroutine just to send a value
 	go func() { cs <- "wordy" }() // again, for cs this time
-	// Select has syntax like a switch statement but is doing something
+	// Select has syntax like a switch statement but each case involves
-	// pretty different.  Each case involves a channel operation.  In rough
+	// a channel operation.  It selects a case at random out of the cases
-	// terms, a case is selected at random out of the cases that are ready to
+	// that are ready to communicate.
-	// communicate.  If none are ready, select waits for one to become ready.
 	select {
 	case i := <-c: // the value received can be assigned to a variable
 		fmt.Println("it's a", i)
@@ -375,37 +271,19 @@ func learnConcurrency() {
 	learnWebProgramming() // Go does it.  You want to do it too.
 }
 
-// A simple web server can be created with a single function from the standard
+// A single function from package http starts a web server.
-// library.  ListenAndServe, in package net/http, listens at the specified
-// TCP address and uses an object that knows how to serve data.  "Knows how"
-// means "satisfies an interface."  The second parameter is of type interface,
-// specifically http.Handler.  http.Handler has a single method, ServeHTTP.
 func learnWebProgramming() {
+	// ListenAndServe first parameter is TCP address to listen at.
+	// Second parameter is an interface, specifically http.Handler.
 	err := http.ListenAndServe(":8080", pair{})
-	// Error returns are ubiquitous in Go.  Always check error returns and
+	fmt.Println(err) // don't ignore errors
-	// do something with them.  Often it's enough to print it out as an
-	// indication of what failed.  Of course there are better things to do
-	// in production code: log it, try something else, shut everything down,
-	// and so on.
-	fmt.Println(err)
 }
 
-// You can make any type into an http.Hander by implementing ServeHTTP.
+// Make pair an http.Handler by implementing its only method, ServeHTTP.
-// Lets use the pair type we defined earlier, just because we have it
-// sitting around.  ServeHTTP has two parameters.  The request parameter
-// is a struct that we'll ignore here.  http.ResponseWriter is yet another
-// interface!  Here it is an object supplied to us with the guarantee that
-// it implements its interface, which includes a method Write.
-// We call this Write method to serve data.
 func (p pair) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	// Serve data with a method of http.ResponseWriter
 	w.Write([]byte("You learned Go in Y minutes!"))
 }
-
-// And that's it for a proof-of-concept web server!  If you run this program
-// it will print out all the lines from the earlier parts of the lesson, then
-// start this web server.  To hit the web server, just point a browser at
-// localhost:8080 and you'll see the message.  (Then you can probably press
-// ctrl-C to kill it.)
 ```
 
 ## Further Reading