Jacek Laskowski (29) [Avatar] Offline
#1
Hi,

Below are my comments on MEAP v2.

Headline: The writing style is well-balanced and flows well while reading. It encourages ongoing reading. There's enough material covered to digest and I didn't feel I'd needed more or less (with just a few comments below). That's what I call 'a well-balanced writing. Thanks!

In Welcome
I doubt that "by the end of Chapter 2, you'll be comfortable reading and understanding most Go code" I'm not, and read Chapter 2 twice. I don't feel in a need to learn more, though smilie Perhaps, in the upcoming MEAP releases.

On page 1
> The cell phone you carry probably has more CPU cores
I think it'd be more readable if it says "has probably more" or "may have more".

On page 1
> but we're still programming for them in the same ways we were when there was just one core.
It'd be more readable if it says "but we're stilll programming using the techniques we've been using for a single core".

On page 2
> In this chapter you'll see why Go is different from other programming languages.
I think it'd be better to list how's not why's and so the sentence should say "In this chapter you'll see how Go is different from other programming languages."

On page 2
> We need something better that provides the benefits of dynamic and interpreted languages with the speed and safety of static and compiled languages.
I'd be very helpful to read what Go offers to support the wish. Just a sentence or two afterwards.

On page 3
> Some languages like C or C++ offer fast execution, while other languages like Ruby or Python offer rapid development.
Is there a reason not to mention Java/Scala or F# when comparing Go to other languages in this sentence/context? I think Scala/F# with the REPL make it viable alternative for rapid development.

It's in many places where it's is used while "its" should be.

On page 5
> Goroutines use less memory than threads and the Go runtime will automatically schedule the execution of goroutines from a configurable pool of threads.
How is this different from Java's Executor framework? I'm asking since you compared Go to Java in this section already and would like to read few sentences about their differences or similarities if there are any.

Is there a difference between method and function in Go?

On page 9
> it means that a type has a specific set of capabilities.
...that the type

On page 9
> You don't even need to declare that you're implementing an interface,
You don't need to declare that you're implementing an interface in Go,

On page 9
> In Go, if your type implements the methods of an interface,
"implements" should be "provides" as the former suggests that it explicitly implements an interface (similar to Java)

On page 11
Section "1.3 Hello, Go" could be earlier in the chapter, perhaps before why's, to get readers familiar with the syntax of Go.

On page 11
The main() function is what gets executed when you run your application - just like in C.
Unless I'm mistaken, the method main gets called only when it's in the package main. I'd make a note of it in the book.

On page 14
> This balance is achieved through a minimized set of keywords
minimized -> minimal?

On page 15
> In this section we will review the Go keywords, built-in functions and standard library.
Add "operators and delimiters" => "the Go keywords, operators and delimiters, built-in functions"

On page 15 and few more
> we have available to us
Remove "to us" and leave "we have available"?

On page 15
> with the keywords and our variables
Remove "our".

On page 16
> Don't confuse the built-in functions with keywords
Could you elaborate on why it's important? I know the difference, but wonder what made the author think it could've been otherwise?

On page 16
Are the list of built-in functions in Listing 2.3 a complete set of all the available built-in functions in Go? It'd be useful to know from the book.

On page 16
> Special care has been taken by the Go language team to create a standard library that will make us very productive. Thanks to the standard library, we can do some very powerful things in a few lines of code.
Give some examples to drive curiosity. I'm in, but am keen to learn few examples right after the paragraph.

On page 18
In Listing 2.5 True and False are both Uppercase - really?

On page 19
> There are several ways in Go we can declare, create, initialize and use variables.
There are two actually = allocate an integer and assign it a value + use a short variable declaration. Are there others?

On page 19
> a variable of type integer is declared
It should say "of type int"

On page 20
> Variable name and then Type information
"Type" lowercase?

On page 20
> The Go language team believes that when reading variable declarations from left to right, it is more natural to have the variable name first.
Add "as it reads a variable of a given name is of type..."

On page 20
> There is a trade off with Go initializing our variables to their zero value.
How could we handle the use case in Go? Scala offers Option to differentiate between no value (None) and Some. Is there something similar?

On page 21
> Go provides the ability to get down to the "bits", so pointers are an important part of the language.
It could be "With pointers, Go provides the ability to get down to the bits".

On page 24
it'd be useful to have visual references (1)'s to the code under discussion (instead of writing "the first assignment statement" or "the second assignment statement") as on page 55 in Listing 3.5

On page 25
> Go allows us to perform explicit type conversions as long as we are converting against compatible types.
What types are compatible?

On page 25
> that is unexported can not.
s/can not/cannot

On page 25
What about changing the section's name from "2.2.5 Exported Identifiers" to "2.2.5 It's all in the first letter - exported identifiers"?

On page 25
> and unexported identifier is
s/is/are?

On page 26
We haven't explained func syntax yet smilie

// (I think I'll just copy the notes with no formatting to ease reading - sorry)

page 26 Listing 2.14 How does alertCounter(0) work? I can only guess, but think it should be explained. Is int(0) possible?

page 26-27 counter.alertCounter -> counters.alertCounter => the package's name is 'counters'

page 27 at the bottom - "User-defined types" in the 2nd sentence in 2.2.6 should start with "They"

page 28 at the top = "Name and Age." => "Name and Age (since their names start with an uppercase letter)"

page 28 = Listing 2.18 = I wish I'd been told how to run the code. What are the options?

page 29 "memory the is" => "memory that is"

page 30 When a struct embeds another with no field name before the embedded struct's name, how are naming conflicts/clashes resolved?

page 32 "Dog Name: %s\n" -> "Dog Name: %s
"

page 33 "...the Parent field are identical" => "...the Parent field is identical"

page 32 "we can use pointers" - why would I need it? What does it buy us?

page 32 "...the pointers points to" -> "...the pointers point to"

page 34 Listing 2.29 (but applies to the book in general and Go) - What can be an identifier? Is the naming convention to have short or long names? What about booleans? Are they named any special, like with '?' at the end as in Clojure to expose their boolean nature by a name?
I would change the name of the variable - result - to keep the computation of isPrimeNumber(5) to be isFivePrime.

page 35 Listing 2.31 - where is the 'result' on the same line as the initialization - can I have it a bigger computation of boolean return type?

page 35 "more compact and readable" - wouldn't using isPrimeNumber(5) directly enough to offer the qualities?

page 35 "the use of A semicolon" => "the use of a semicolon"

page 36 Listing 2.33 "System Warnings Detected" => "System Warning Detected"

"2.3.2 Iteration" => "2.3.2 Iteration - it's all about for"

page 39 Listing 2.37 "The other change we made is with the default case" => what would the program do without the Loop label in break? Wouldn't it also work as it's now? "This form of break will cause the program flow to immediately move outside of the for loop and to continue on past the for statement" suggests so.

page 40 Move "and in some cases uncommon and unique" between parenthesis.

page 40 "One feature we have available to use in Go" -> "Another feature of Go"

page 40 Listing 2.38
fmt.Printf("ERROR: %s", err) - no '
'?
user"} -> user}

page 40 "...on the same line as the func keyword." -> "...on the same line as the func keyword (like loop and switch)."

page 41 "...is to use a blank identifier" -> "...is to use a blank identifier - an underscore - "

page 41 Listing 2.39
fmt.Printf("ERROR: %s", err) - no '
'?

page 41 Listing 2.40 + page 42 Listing 2.41
user"} => user}

page 45 about Error Handling - is there a convention to place error return parameter last in the return parameter list?

page 46 Listing 2.47
fmt.Printf("unable..."smilie -> U uppercase
"...error: %s" => add '
'
In 2.5.2 page 46
"...are implemented as a panic" -> is this a type or a function?
"...to throw similar errors" -> similar to what?!
page 46 Listing 2.48
defer uses an anonymous function = it should be explained how such functions are implemented.
%v -> is this the formatting for errors? Add a note what it does.

I'd like to see a bit about Go REPL if that's available at all. What are the steps to run the samples? It's so temping to give them a go (pun intended).

page 48 "you should have Go installed according to the guidelines in the preface of this book." - were there any giodelines? I may have missed them.

Is .go a required extension for Go programs?

page 50 "instead of a library to be used inside other libraries, or programs." -> "instead of a library (to be used inside other libraries, or programs)."

page 50 "-- called packages in Go --" - remove it as it was already explained. Gives a feeling it's the first time mentioned here.

page 50 "it's name" -> "its name"

page 50 "inside GOPATH/src/hello" - where was the GOPATH defined? Is it required to place fo packages under GOPATH?

page 51 "you're telling the compiler" -> "you'd have been telling the compiler"

page 51 after Listing 3.2 Add a few words on the package with a single main function that it shares nothing and hence the only reason to have it is to develop a new command in Go.

page 51 Can I use a package without importing it first?

page 53 How does Go know that a package needs to be downloaded? Does the import need to reflect it somehow or whatever the import when it's not locally available, Go will attempt to download it?

page 53 3.2.2 could be changed to "Package aliasing - importing by another name" or just "Package aliasing"

page 54 Listing 3.4 "Go in Action" consistent in two Println's.

page 54 NOTE could be moved to Chapter 2 where it was first used to ignore a return value in Listing 2.39.

page 55 Listing 3.5
the title is the file name - it's not consistent with the other listings - either file name or what a package does
Why does the code use new(PostgresDriver) rather than PostgresDriver.New() which was told very idiomatic on page 28?

page 55 "left out it's definition" -> "left out its definition"

page 56 "3.4 Using Go Tools"
"You've been using the go command for a few chapters now." -> few chapters?! I've been using it?! I may have missed that. It was just in Chapter 3 where we started a bit of using the go command. And it's not very often.

page 56 It's only on the page where the go command was used on the command line. I think we could move it to earlier pages.

page 58 Listing 3.7
the listing's name is the file name. It's good, but not consistent with the other listings.
fmt.Println("There was an error opening the file:", err) -> should be fmt.Printf with "%v
"
fmt.Printf("There are %d words in your text. n", count) -> should be '
'

page 58 "If you've downloaded the source code for the book." - there was only a note in Welcome how to download the sources - people might not know how to work with git. I think it deserves a section.

page 58 "If your terminal session was currently in folder in $GOPATH/src/chapter3 called wordcount" -> "If your terminal session was currently in $GOPATH/src/chapter3/wordcount"

page 59 + page 60 Be consistent with the use of command line's prompt - it's in "go build"'s and "go run" + "go vet"

page 60 Listing 3.8 Missing '
' in Printf.

page 60 Is there a way to execute go vet before go run or after go compile?

page 61 No space in 'err!= nil'

page 65 at the end of "Package should live at the root of the repository" section - Could we have some examples on how to lay out a public repository on GitHub or code.google.com with screenshots or a tree-like listing?

page 65 "before you check anything in" -> "before checking anything in"

Jacek
brian.ketelsen (14) [Avatar] Offline
#2
Re: Comments on v2 - all three chapters
These are great comments! Thank you so much.
danoand (3) [Avatar] Offline
#3
Re: Comments on v2 - all three chapters
Proposed code snippet change for Listing 2.36 on p. 38 of v02:

Change:

count < 10

To:

count > 10

If the reader is running this code it illustrates the iteration with a little more meaning with respect to implementing an infinite loop including a "break"