Manning Forums: The first two chapters are horrible. ...

codyk

Posts: 2
Registered: 10/31/09

The first two chapters are horrible.
Posted: Nov 1, 2009 11:54 AM

Reply

Random harsh-but-heartfelt criticism:

In section 1.2, add isn't a clojure function

Everything in clojure isnt a symbol or a list, there's no reason to lie
here. You can make the generalization you want about
evaluation without it - unquoted lists are generally evaluated by
looking up the first thing in the list and applying it to the rest of
the things in the list.

"language-level construct that allows code-generation and
transformation at run-time" . . .
macros are not run-time constructs, they are post-parsing, pre-compilation constructs.

Section 1.2.1 long xml digression in response to "too many parentheses" . . . IMHO
the points that need to be made about parens are:

1. There aren't necessarily more or less parentheses, they're often just in different places
(f x) instead of f(x)
2. editor takes care of balancing parentheses for you, you should
never be counting closing parentheses for instance.

Make sure code is formatted idiomatically, ie 1.2.1 def a-map shouldn't have braces as
the last or first character on a line.

You make frequent generalizations about other languages without any actual examples to back them up.
In section 1.3.1 clojure is different because it has a JIT? Pfft.
The implication in section 1.3.2 that you cant do the equivalent of map filter etc in ruby is stupid.
Stop making generalizations about or comparisons to other languages, except java, and then only with specific examples.

I lost count of how many times you mention the word "power",
in regard to the interaction between lisp syntax and macros.
Show don't tell. If you need a simpler example than the java
boilerplate, do a postfix or infix evaluation macro, that way you can
actually show the defmacro.

The only interesting technical points about lisp macros in general are

1. they control evaluation
2. they control lexical environment
3. they use the language itself, not a separate preprocessing language

The tradeoff is that in exchange for extremely regular syntax, you can have
any semantics you want; as long as you write code that looks like
lisp, you never have to write repetitive boilerplate again. Show that
point clearly, then drop all of the "power" nonsense. Other languages
make different tradeoffs (template haskell / meta ocaml), and it
doesnt necessarily mean they are less powerful.

The typical duplication in java code example listing 1.3 cant actually be
run without definitions for create-audit-log etc. Instead, use an example of
java's file open try / catch / finally vs clojure's with-open.
That way you only have to worry about there being a
file in the working directory the reader can open.

This is actually indicative of a more pervasive problem. Most of your
examples, while they're intended to look meaningful, won't actually run
if someone copies them into a repl.
Write code examples in an actual editor & run them; make it explicit
when code shouldn't run or what prereqs are necessary.

If someone's going to run the examples in a repl, they're going to
need a working clojure install.
Assuming people can install git and ant on their own doesn't cut it.

The choice of topics in chapter 2 baffle me; how is try / catch
something that needs to be explained in detail before doc and find-doc (doc at
the very least needs to be mentioned early), much less before "if" ?

Your let form example of binding _ to result of println in section 2.2.2 is horrible.
There is no reason ever to do that.
println would be in the body of the implicit do block, not in the bindings.
You'd be better off spending some time explaining why lexical variable assignment is called "let"

Another meaningless generalization, "pure functional languages do not have state at all" in 2.2.3

GHCi, version 6.10.3: http://www.haskell.org/ghc/ :? for help
Loading package ghc-prim ... linking ... done.
Loading package integer ... linking ... done.
Loading package base ... linking ... done.
Prelude> x
<interactive>:1:0: Not in scope: `x'
Prelude> let x = 10
Prelude> x
10

How is that not state? Constraining the mutability of state is not
the same thing as state-free.

I'm sure you have many useful and interesting things to share
regarding your real world experiences with clojure. Go write those
chapters first and get your legs under you, because frankly your
attempts at basic pedagogy suck, and they suck in a way that cant be
fixed by correcting a few typos here and there. The first two chapters are
confusing, smack of smug lisp weenieism with insufficient justification,
and would be a black eye on the clojure community if released as is.

amitrathore

Posts: 86
From: Silicon Valley, CA
Registered: 10/27/09

Re: The first two chapters are horrible.
Posted: Nov 1, 2009 2:31 PM

in response to: codyk

Reply

Thank you for taking the time to write out your feedback. This is the first time I'm writing a book, so by no means is it going to be anywhere near perfect. Any and all criticism is welcome. Several of your points are valid, and I will go over your post in detail to extract those changes that I can make that will improve the chapters.

More specifically, it is true that I've made several generalizations in order to make my points easier to understand. And from reading your other posts on Lambda The Ultimate forums (http://lambda-the-ultimate.org/user/2921/track), I can understand that someone like you would get riled up over some of things I say in these chapters. I will improve some of the statements you object to

Also please remember that not everyone reading the book is a language enthusiast like yourself - for instance, I've gotten feedback from several folks that the XML example actually helped them understand the "syntax" of Lisp. I can certainly add the points you make about the placement of the parens.

Your point about code not being REPL-friendly is valid, I'm going to try to improve it. The first chapter is meant more as a high-level intro than as a get-your-hands-dirty-right-away chapter. Maybe that's not what people want, we'll see.

About using the word "power" - point taken! I just counted, and I'm embarrassed to report that it's used 33 times in chapter 1 (and another 6 times in chapter 2). That's easily fixable.

There's more valuable feedback in your post, I'll comb through it and apply what I can.

Again, please keep the feedback coming. I'm open to suggestions/fixes/criticism, and that's what this forum is for, and is what will make the early-access program successful. Thanks again!

bbaron

Posts: 29
From: earth
Registered: 9/28/08

Re: The first two chapters are horrible.
Posted: Dec 3, 2009 7:46 AM

in response to: amitrathore

Reply

Lambda may not be the Ultimate any longer:
Fatal error: Table './ltu/sessions' is marked as crashed and should be repaired query: SELECT u.*, s.* FROM users u INNER JOIN sessions s ON u.uid = s.uid WHERE s.sid = 'd7f7cb36f8249ad127c7ce6fc6dbaf80' AND u.status < 3 LIMIT 0, 1 in /home/vhost/ltu/www/includes/database.mysql.inc on line 66

As the functional programming paradigm is becoming more mainstream these days, it's going to be fascinating to see how the academic purists react to the inevitable "dumbing down" of the use of clojure by IT department and body shop code monkeys.

Tcepsa

Posts: 28
From: Just outside Baltimore, MD
Registered: 12/7/09

Re: The first two chapters are horrible.
Posted: Dec 7, 2009 5:21 PM

in response to: codyk

Reply

I'll vigorously second the sentiment that the example code should run in the REPL, and you should get users up and running the REPL ASAP (possibly in an introductory section before Chapter 1 if you don't want to actually put it in Chapter 1, or in an Appendix--which you then point users to very early on--if you feel that it is secondary to the actual material, though I don't know that buried-at-the-back-of-the-book is a good place either...)

Considering that the title is Clojure in Action, I want to be taking action with Clojure right away, not trying to figure out why the examples don't work. (Another author--whose work proved invaluable to me in learning Java--recently suggested that writers ask themselves three questions which I paraphrase as: What's your page-turning strategy (i.e. how do you keep readers engaged and turning the pages)? What is the number of pages before the reader actually does something? What is the number of pages until the reader feels something? I'd encourage you to consider them as you're arranging the book.)

andrews

Posts: 1
Registered: 1/23/10

Re: The first two chapters are horrible.
Posted: Jan 23, 2010 2:55 AM

in response to: Tcepsa

Reply

As a newcomer to Clojure, I'd like to second the point that the first two chapters are unnecessarily confusing and frustrating introduction to the language.

I think that if the first chapter is intended to be a high-level introduction to the concepts and advantages of the language then perhaps it would be better not include code examples here at all. If the chapter hasn't yet spoken about particular forms or data types then including them in examples can just confuse the reader and obscure the point being made. I think it's absolutely fine to talk about high-level concepts without illustrating them with code fragments and would favor removing them, or deferring discussion of the high-level concepts until the reader is familiar with the syntax used in the examples.

In the second chapter, would it not make more sense to discuss data types before program structure? The data type discussion is clear and well explained, but the examples used in the program structure are again unnecessarily confusing by trying to look like real programs rather than toy examples. I'd favor showing examples that use the basic data types. For example, why not show map/filter/reduce operating on simple lists of numbers rather than some hypothetical expense calculation?

I'd also favor swapping the order of the two chapters so a more hands-on, basic introduction is first. The first chapter makes a lot more sense if the second has been read first.

For what it's worth, I thought the third chapter was much, much better and renewed my interest in the book. I'm looking forward to later chapters -- keep them coming!

amitrathore

Posts: 86
From: Silicon Valley, CA
Registered: 10/27/09

Re: The first two chapters are horrible.
Posted: Jan 23, 2010 12:47 PM

in response to: andrews

Reply

Andrews,

Thank you for taking the time to write in... I'm hoping you'll continue to like the quality of the chapters (at least 3 and up...)

I've got mixed feedback about the first two chapters (minus this thread

) I will be revamping them a fair bit before the book is done. Thanks again, and please keep the feedback coming!