Comments on fastidious-flounder

[JuanManuel Gimeno Illa]

Some notes and comments on fastidious-flounder:

- in 14.1 I think it is better to use * rather than x for the expansion of the factorial.

- in 14.1 you say: "Pattern matching works particularly nicely for recursive functions because it distinguishes clearly between the ending case or cases (which are constants) and the recursive cases (which have symbols)." Maybe I'm overstrict, but there exist recursive functions where the base case is not a constant. So I suggest rephrasing it as "for many recursive functions ...."

- 14.3: I suggest using neg? rather than (partial > 0) which, as you say in the book, reads awkwardly.

- 15.1: In the function make I find the name of the parameter "values" misleading. I'd use "value"

- 15.1: In oo-style definition I'd would use destructuring (which has been use extensively in the previous chapter):

          (def oo-style

                (fn [this & args] (type this)))

- 16.1 and 16.2: In the maybe-monad the parameter is called continuation and in the sequence-monad, monadic-continuation which is misleading.

- 16.2: In the first paragraph you say that the decider is what clojure.algo.monads calls m-bind, but in the last example of 16.1 you use both m-bind and m-result (and you say that what you call monadifier is called m-result). Better to clarify m-bind and m-result in 16.1 in the same paragraph.

-17.1: In the first definition of calculation you use the m-result defined in the function monad. Is the same function monadifier you define at the begining of 17.1? It it is so, why don't you use it? 

-17.1: In the definition od the function-monad you return to the continuation parameter, not monadic-continuation.

-17.4: In the (calculation-with-initial-step -88) the value -88 is misleading because inside the function you use 88 as the new value.

-------------------

PS: Yesterday I was in a hurry, so I didn't finished the explanation about the loop in the print function. The whole explanation is that destructuring usese nthnext to access the &elements, so when it destructures [[x & xs] xs]

- it uses (first xs) for x, so it asks for one element of the sequence

- it uses (next xs) for xs, which is (seq (rest x2)) and seq needs to know whether the rest is empty or not, so it need to ask for another element.

That's, I think, the whole explanation for the print.

-------------------

Juan Manuel

[Julian Gamble]

I've got some additional comments on fastidious-flounder - Introduction and Chapter 1. 

 - on page 6 of 14 of the Introduction - the book refers to to 'structure sharing' - when I cast my eyes over it - I was expecting to read "structural sharing."

 - on page 3 of 49 in Chapter 1 - light table has a screenshot and leinengen has none. It feels unbalanced - almost like leinengen is the lesser cousin. 

 - on page 7 of 49 - there is a reference to 'studlyCaps' - when I was expecting camelCase

 - on page 24 of 49 - there is talk about not having an assignment statement. The concept the book is trying to convey here is 'reassignment' - or changing assignment. I think this could be clearer - as it is quite fundamental

 - on page 29 of 49 - there is a reference to "first year programming" - this assumes the reader went to college/university, and is not a self taught enthusiast - or high school student. This could be clearer - it feels a little offhand.

 - on page 35 of 49 - there is a reference to 'prn' - now there are about 4 different ways of printing a string in Clojure - is it worth having a brief footnote on why they're different? Why is this one chosen as the best?

Just my 2c. 

JG

[Brian Marick]

On Oct 9, 2012, at 6:09 AM, Julian Gamble wrote:

> I've got some additional comments on fastidious-flounder - Introduction and Chapter 1.

Addressed all of your comments in some way, except for:

> - on page 7 of 49 - there is a reference to 'studlyCaps' - when I was expecting camelCase

You kids and your new-fangled terminology. I remember reading "StudlyCaps" on Lisp mailing lists in the 80's, and I continue to use it out of reverence for tradition. (And if I misremember, I don't want to know it. Harrumph.)

-----
Brian Marick, Artisanal Labrador
Contract programming in Ruby and Clojure
Occasional consulting on Agile
Writing /Functional Programming for the Object-Oriented Programmer/: https://leanpub.com/fp-oo

[Julian Gamble]

On Wednesday, 10 October 2012 09:49:38 UTC+11, Brian Marick wrote:

On Oct 9, 2012, at 6:09 AM, Julian Gamble wrote:

> I've got some additional comments on fastidious-flounder - Introduction and Chapter 1.

>  - on page 7 of 49 - there is a reference to 'studlyCaps' - when I was expecting camelCase

You kids and your new-fangled terminology. I remember reading "StudlyCaps" on Lisp mailing lists in the 80's, and I continue to use it out of reverence for tradition. (And if I misremember, I don't want to know it. Harrumph.) 

Fair enough. You question was 'what interrupted your chain of thought?'. 

Happy to keep it as it is - just pointing out you'll need to explain it. 

JG 

[Julian Gamble]

I've got some additional comments on fastidious-flounder - Chapter 2 and following:

 - "| Embedding an Object Oriented Language [title page]" perhaps this formats incorrectly on the iPad - but this looks like it starts with an I-bar. It's not really clear whether this is a "Part 1" - which feels strange after the first chapter - or something else. 

 - Ch 3 - A Barely Believable Object

* p 6/12 - you need to explain to the reader that __class_symbol__ is just a name (and a naming convention) that you have made up. The inexperienced reader might assume that this name or naming convention might have special significance in Clojure.

* p7/12 - references to 'peyote' don't really have a meaning outside the United States - probably better to insinuate using 'magic mushroom'

- Ch4 - All the Class in a Constructor

* perhaps the title should be "All of the class in a Constructor"

* p2/5 - you need to explain the references to __methods__ as above. Not clear whether this is your naming convention (to the inexperienced reader) or just some poorly documented feature of clojure

- Ch 5 - perhaps this title should be "From a Constructor container to a Class container" - to clarify that you're still using both - just switching them around. 

Just my 2c. 

Cheers

Julian

[Brian Marick]

On Sep 30, 2012, at 10:34 AM, JuanManuel Gimeno Illa wrote:

> Some notes and comments on fastidious-flounder:

Addressed all of these.

Also, regarding:

> - 14.3: I suggest using neg? rather than (partial > 0) which, as you say in the book, reads awkwardly.

WHY DID NO ONE TELL ME OF `neg` BEFORE?

[Brian Marick]

On Oct 10, 2012, at 5:08 AM, Julian Gamble wrote:

> I've got some additional comments on fastidious-flounder - Chapter 2 and following:

Addressed all, except:

>
> - Ch4 - All the Class in a Constructor
> * perhaps the title should be "All of the class in a Constructor"

The title is an obscure reference to Blake's "Auguries of Innocence". An easter egg, if you will.

To see a world in a grain of sand
And a heaven in a wild flower,
Hold infinity in the palm of your hand
And eternity in an hour.

The title as is matches the pattern of stresses in Blake's first line better than your alternate wording:

to SEE a WORLD in a GRAIN of SAND
- ALL the WORLD in a CON struc TOR

Sometimes I indulge myself in a sort of pseudo-intellectual whimsy. Changed the other chapter title, though, to "Moving the Class Out of the Constructor"

[Julian Gamble]

I've got some additional comments on fastidious-flounder - Chapter 6 and following:

* 6 - Inheritance (and recursion)

 - p 28/44 - You have this great explanation of recursion - and how TCO can be implemented by representing calls as cons to use less memory. You almost go as far as how you would implement a fixed point combinator in Clojure - and then walk away from it. You go on to talking about recursion in Clojure using recur - and completely miss the opportunity to bring up the y-combinator point you were building up to. 

* 7 - The Class as an Object

 - p 1/17 "I don't much like the function a". If you mentioned this before then I missed it. If it was important - can you please reference the chapter where you mentioned it? If you haven't explained it before - can you explain it here?

* II - The Elements of Functional Style

 - This would be so much clearer (when read in a sans-serif font) if you changed the "II" to "Part II"

* 8. Types that flow through functions

 - p4/42 - "number of registrants". I don't think this is a word. I think the word you're looking for is "attendee" or "student". 

 - p8/42 - "Ick". This is not a complete sentence. It stands out to the reader. Perhaps "This is icky". 

[Brian Marick]

On Oct 10, 2012, at 11:15 PM, Julian Gamble wrote:

> I've got some additional comments on fastidious-flounder - Chapter 6 and following:
>
> * 6 - Inheritance (and recursion)
> - p 28/44 - You have this great explanation of recursion - and how TCO can be implemented by representing calls as cons to use less memory. You almost go as far as how you would implement a fixed point combinator in Clojure - and then walk away from it. You go on to talking about recursion in Clojure using recur - and completely miss the opportunity to bring up the y-combinator point you were building up to.

I had a chapter specifically about letfn and Y, but I decided Y is something more for the language/theory geek than my target audience. Still toying with taking some of the omitted topics and putting them into a book titled /Turtles All the Way Down/.

> * 7 - The Class as an Object
> - p 1/17 "I don't much like the function a". If you mentioned this before then I missed it. If it was important - can you please reference the chapter where you mentioned it? If you haven't explained it before - can you explain it here?

Don't understand. `a` is a function I had you write in an earlier exercise set; it's been used since then. It's what earlier chapters used instead of `new`, which is a reserved word in Clojure. In any case, prompted by this, I went and changed all uses of `a` to `make` in the next version.

>
> * II - The Elements of Functional Style
> - This would be so much clearer (when read in a sans-serif font) if you changed the "II" to "Part II"

That's Leanpub's house style. I don't have any control over it.

> * 8. Types that flow through functions
> - p4/42 - "number of registrants". I don't think this is a word. I think the word you're looking for is "attendee" or "student".

It's been in English since 1890.

One of the cool things about English is the way its speakers make new words by chopping up or adding to old ones. Did you know that the verb "edit" came from chopping the last two letters off of "editor" and that "asset" came from "assets" (which was not originally plural but became a plural once "asset" came into being)?

A cool one: the verb "escalate" comes from "escalator". I wouldn't have imagined the noun came first, but the noun was made up by its inventor in 1900. The verb originated in 1922. It only came to take on the meaning of "to increase or develop by successive stages; spec. to develop from 'conventional' warfare into nuclear warfare" in 1959, possibly in honor of my birth that year.

Ain't the internet a grand way to get distracted?

> - p8/42 - "Ick". This is not a complete sentence. It stands out to the reader. Perhaps "This is icky".

I can't remember where I picked up that style - picture with one word caption that's a commentary - but it's always struck me as clever. Think of it as just another of my lovable quirks.

[JuanManuel Gimeno Illa]

Still toying with taking some of the omitted topics and putting them into a book titled /Turtles All the Way Down/.

+1

 

 

[Julian Gamble]

On Friday, 12 October 2012 07:08:30 UTC+11, JuanManuel Gimeno Illa wrote:

Still toying with taking some of the omitted topics and putting them into a book titled /Turtles All the Way Down/.

+1

But you're saying your next book won't be this one - it will be one on programming functionally in Ruby right? Something along the ideas of the Hamster library? 

[Julian Gamble]

I've got some additional comments on fastidious-flounder - Chapter 9 and following:

* Chapters 9-12 flow really well - and nothing really jumped out at me. The only thing that niggled as I reflected on it was that it felt like you spent less time building ideas here, more more time making assumptions about the readers knowledge and jumping into the code. This seems to depart from the stye of the beginning of the book. Perhaps you'd consider dividing these three chapters into 10 page chunks - and just adding a page of prose explaining the big idea you're driving at.

* 13 - Putting Bookkeeping into the Runtime: Laziness and Immutability

 - very inspired subject matter for this chapter - good job

 - p 5/15 - "Even more than Object Oriented languages do, they hide from you the awkward truth that the story C tells is the true one." Perhaps you'd consider "Even more than Object Oriented Languages do, functional languages hide from you the truth about your data that in C would otherwise be transparent". 

 - p23/51 - "... returns a new Java object, it must new it up". Consider replacing this with "... returns a new Java object, it must instantiate it with new."

* Ch 15 - Generic functions

 - "I'm unsure if I want to include this chapter...". You totally should!

 - p 9/26 - I really like the asteroid subject matter. You should consider adding a link to the Bob Martin Clojure asteroid example - just for the fun of it.

 - p 19/26 "the double dispatch problem". This is quite hard to wrap your head around. You might want to include an object diagram here. Perhaps even give an example of the problem in a non-Clojure language like Java. 

[Julian Gamble]

I've got some additional comments on fastidious-flounder - Chapter 17 and following:

* 17 - Functions as Monadic Values

 - p22/25 [Here you illustrate the State monad by comparing I/O in Clojure and Haskell]. In my view this illustration is critical to the whole discussion about monads. You should move this paragraph right back to the beginning to when you first start talking about monads. (This is a similar illustration to what SPJ uses when presenting). 

 * IV Glossary

 - p10/24 - "macro - a function that translates Clojure code into different Clojure code". In this talk (http://vimeo.com/45695419) - Christophe Grande explains that this is only true from the point of view of the reader, but what the reader sees as the output of a macro is different to what a human being might expect (ie symbols replaced with identity references). Perhaps you'd consider adding "…into different Clojure code for the reader". 

 - p17/24 - "software transactional memory" - perhaps you should mention MVCC in here. 

 - p18/24 - "structure sharing" - consider "structural sharing"

 - p19/24 - "value" - I have this niggling suspicion that this definition isn't clear enough after Rich Hickey's talk on "value of values". I think your definition needs to specify what is excluded from being a value. 

 - p21/24 - "The Little Schemer" - perhaps you should include the publication date of the one you did read. Perhaps it was "The Little Lisper" then. I have read and own the "Little Lisper" 1989 edn". 

* Table of Contents

 - Why is this at the end of the book? Surely this is a leanpub bug? (The TOC metadata for the stanza app works well tho)

Just my 2c. 

Cheers

Julian Gamble

[Brian Marick]

On Oct 12, 2012, at 6:46 AM, Julian Gamble wrote:

> But you're saying your next book won't be this one - it will be one on programming functionally in Ruby right? Something along the ideas of the Hamster library?

I'm not sure what the next book will be.

[Brian Marick]

On Oct 12, 2012, at 6:55 AM, Julian Gamble wrote:

> I've got some additional comments on fastidious-flounder - Chapter 9 and following:
>
> * Chapters 9-12 flow really well - and nothing really jumped out at me. The only thing that niggled as I reflected on it was that it felt like you spent less time building ideas here, more more time making assumptions about the readers knowledge and jumping into the code. This seems to depart from the stye of the beginning of the book. Perhaps you'd consider dividing these three chapters into 10 page chunks - and just adding a page of prose explaining the big idea you're driving at.

When I do a next read-through of Part II, I'll keep this in mind. Added it in the issue tracker.

> - p 5/15 - "Even more than Object Oriented languages do, they hide from you the awkward truth that the story C tells is the true one." Perhaps you'd consider "Even more than Object Oriented Languages do, functional languages hide from you the truth about your data that in C would otherwise be transparent".

What don't you like about the first version?

>
> - p23/51 - "... returns a new Java object, it must new it up". Consider replacing this with "... returns a new Java object, it must instantiate it with new."

Fixed

>
> - p 9/26 - I really like the asteroid subject matter. You should consider adding a link to the Bob Martin Clojure asteroid example - just for the fun of it.

Wow. I hadn't realized how common asteroid collisions were for explaining double dispatch. Here's wikipedia:
http://en.wikipedia.org/wiki/Double_dispatch

I honestly thought my example was original, but I must have read the original asteroid example years and years ago. (I first learned about double-dispatch in Smalltalk in 1984.)

> - p 19/26 "the double dispatch problem". This is quite hard to wrap your head around. You might want to include an object diagram here. Perhaps even give an example of the problem in a non-Clojure language like Java.

I'll work on that.

[Julian Gamble]

On Saturday, 20 October 2012 09:00:03 UTC+11, Brian Marick wrote:

On Oct 12, 2012, at 6:55 AM, Julian Gamble wrote:

> I've got some additional comments on fastidious-flounder - Chapter 9 and following:
>

>  - p 5/15 - "Even more than Object Oriented languages do, they hide from you the awkward truth that the story C tells is the true one." Perhaps you'd consider "Even more than Object Oriented Languages do, functional languages hide from you the truth about your data that in C would otherwise be transparent".

What don't you like about the first version?

Try saying the first one out loud to a rubber duck. It's quite an awkward sentence that makes a number of assumptions about the reader's knowledge of C. 

JG 

[Brian Marick]

On Oct 19, 2012, at 7:28 PM, Julian Gamble wrote:

> Try saying the first one out loud to a rubber duck. It's quite an awkward sentence that makes a number of assumptions about the reader's knowledge of C.

Don't have a rubber duck. I do have a plush ankylosaurus and a plush shoggoth. I'll see what they think.

[Brian Marick]

On Oct 13, 2012, at 7:52 AM, Julian Gamble wrote:

> I've got some additional comments on fastidious-flounder - Chapter 17 and following:
>
> * 17 - Functions as Monadic Values
>
> - p22/25 [Here you illustrate the State monad by comparing I/O in Clojure and Haskell]. In my view this illustration is critical to the whole discussion about monads. You should move this paragraph right back to the beginning to when you first start talking about monads. (This is a similar illustration to what SPJ uses when presenting).

I'm not convinced that the IO monad is a compelling example outside Haskell. Unless you're already committed to that level of purity, creating a whole new superstructure for something that's already easy to do (`println`) seems odd.

>
> * IV Glossary

I'll look at the talks and see how they should change my definitions.

>
> - p21/24 - "The Little Schemer" - perhaps you should include the publication date of the one you did read. Perhaps it was "The Little Lisper" then. I have read and own the "Little Lisper" 1989 edn".

If I can find it, I will. (I actually liked /The Little Lisper/ better than the Scheme rewrite.) Side note: the way I draw objects and classes, and the "look left, then up" way of describing inheritance comes from a Ruby book I was writing in the style of /The Little Lisper/: http://www.exampler.com/little-ruby/ Never finished, but I'm still fond of it.

> * Table of Contents
>
> - Why is this at the end of the book? Surely this is a leanpub bug? (The TOC metadata for the stanza app works well tho)

That's peculiar. Does that also happen with the garrulous gastropod release? Maybe it's a bug in the leanpub tool chain. In Preview on the mac, the table of contents is in the front, as you'd expect.