On Wed, May 18, 2011 at 12:16 PM, Gregg Williams <greg...@innerpaths.net> wrote: > Steve Yegge's main idea, that "Clojure needs to start saying yes," is > true on multiple levels.
Well, there's always some truth in most of his rants but I'm not sure I'd agree that the main thrusts of this particularly rant are true - he conflates too many issues to be able to discuss it holistically (unfortunately). > Clojure needs to start saying yes...to newcomers. I've actually found the Clojure community to be one of the most welcoming and most helpful of almost any technology that I've picked up in about 30 years. YMMV, I guess, and I'm sure it depends on your programming background. > That's a pretty self-evident statement to make, isn't it? If curious > programmers have a bad initial experience with Clojure, they'll just > leave. And I think this is happening. A lot. Hard to tell how much it's happening really but I will concede that I've seen a number of people struggle with the instructions here: http://clojure.org/getting_started Let's walk thru the process from a complete n00b's p.o.v. (since this is the Getting Started page)... First thing discussed, the github repo. If I go there (not wanting the source but being hopeful about a download), and click Downloads, and pick either the .tar.gz or the .zip options, I get an archive of source code. Fail. Let's try other downloads offered (since I don't want "alpha" anything)... clojure-1.2.0.zip looks promising... OK, it is a full source download but it *does* include a .jar file and java -jar clojure.jar does actually start a REPL. Not a great experience but it sort of works. Back to the Getting Started page to see what next.... CLR? Nah. Development collaboration on JIRA? Nah. Feedback and discussion on the Clojure Google Group? Not clear that's going to help a n00b (but it would!). Link to Clojure Programming wiki. OK. (who maintains that and how up-to-date is it?) Explanation of what's in the download... Far more than a n00b needs to know (bytecode library? really?)... Suggestion: Under "Setup" at the top, provide a link to the Downloads page: "Clojure releases can be <a href="http://clojure.org/downloads";>downloaded here</a>." Then simplify the rest of the setup section so it's clear what a n00b really needs. Under "Editing" further down, change the Getting Started link to point here: http://dev.clojure.org/display/doc/Getting+Started (it points to, and mentions, the old Assembla site). > The Clojure community is, overall, newcomer-hostile. I think that's a broad overstatement, at best. See above - I've found the community to be immensely helpful and welcoming. I think there is a (fairly reasonable) expectation that developers picking up a new language are willing to do _some_ amount of background reading and experimentation rather than expecting everything to be handed to them on a plate, especially with a language as new as Clojure. > Clojure.org is probably many newcomers' first exposure to the > language. On the "Functional Programming" page, the second page with > actual code in it, the reader is introduced to the defn keyword as > follows: I agree that showing (defn hello "Hello world") first would be a better experience for n00bs here and it's definitely arguable that this page could use some love to make it more approachable. I think a better approach would be to agree on a standard "learning Clojure" site (perhaps the Clojure Programming wiki?) and direct folks there for an introduction to Clojure. > Imagine being a newcomer to the language, probably someone who is > unfamiliar with any version of Lisp. Look at the terminology. What is > "arity overloading"? What is a "single function object"? What does > "self-reference" refer to? What does "using &" mean? And how does the > code sample work? I thought the code was pretty easy to understand and all of those terms were familiar to me except for the use of &. I remember when I first read that page and thought "OK, argcount empty list is zero, argcount singleton list is one, argcount two element list is two, argcount two plus something list is... hmm... add argcount two elements to count of the something... that must mean that & more is the rest of the arguments... that's kinda cool!". I didn't fully understand it but it pointed me in the right direction. > Let's say the newcomer is lucky enough to get a REPL working. He > decides to use the built-in help system to find out more about defn: Now, I will say here that most n00bs I've seen exposed to the REPL expect two things to "just work": 1. typing help or (help) should display _something_ useful (even if it's just a link to the docs), 2. typing exit, (exit), quit or (quit) should exit the REPL (if we tell them control-d works in advance, problem solved). Both of those could be solved fairly easily - if only by making sure that both points are addressed on every "official" Getting Started page when the REPL is first mentioned (i.e., a brief mention in the documentation, rather than changing the code). > Now imagine you're the newcomer who's used to looking at Java code. > > Look at "([name doc-string? attr-map? [params*] body] [name doc- > string? attr-map? ([params*] body) + attr-map?])". > > Which of these characters are actually something you'd type, and which > are notations that you *don't* type? I'd instinctively expect something? to be optional and something* to mean zero or more. Basic regex and something I've seen in documentation for decades. I'm genuinely surprised you're asserting there are developers out there who would not know that (I'm not denying the possibility, just expressing surprise - it simply wouldn't have occurred to me). > What's an "attr-map"? An attribute map... map of attributes... so it's some name/value pairs. It's optional so I wouldn't worry about it at first - I'd expect to see it in a definition at some point and try to figure it out from that. Perhaps I'm just used to reading language syntax specifications? > What's the format for a "doc-string"? I'd assume a plain ol' string used (somehow) for documentation unless something told me otherwise (such as an error message or some documentation). And it's optional so I probably wouldn't worry about it until I saw some code - at which point it's pretty self-explanatory. > There's *nowhere* on the clojure.com site > that tells you--or even give you hints on--how to make sense of this. Hmm, you are right that doc-string is not explained on clojure.org. It's mentioned in passing on the Special Forms page but that's it. Fortunately, nearly all real Clojure code seems to have obvious, readable doc-strings so I don't think people would be in the dark for long. > Rich Hickey likes to use single-character variables And the Library Coding Standards page emphasizes that: http://dev.clojure.org/display/design/Library+Coding+Standards (I'm surprised it doesn't recommend k / v for key / value when dealing with maps) When I programmed in FORTRAN (and early Algol-family languages), it was common practice to use i, j, k for loop indices so this doesn't seem odd to me (and even today, programmers the world over tend to assume i, j, k are loop indices and n is some sort of size / count). > code in bloggers' articles often shows off Clojure's elegance through brevity > and minimalism. But isn't that part of the whole attraction of a Lisp? Code is elegant because it is minimal, simple, brief... > I find this last point a lot in blog entries, sometimes even in > Clojure tutorial books: the author leaves several steps of learning > implicit and assumes the reader will infer them from the code itself. That is certainly a valid complaint to make to specific authors and I'm sure most authors would appreciate such feedback since it would help them get their message across better to their readers. I know I always appreciate feedback that helps me write better blog posts. > Talk to newcomers on > *their* terms; make them feel welcome. Remember that you once had > trouble understanding things about Clojure, and frame your answers in > ways that would help the old "newcomer" you. Spend just a little time > taking one newcomer under your wing. Last week I gave an Introduction to Functional Programming talk at a CFML conference. I mostly used Clojure as the example language (although I also had some CFML examples). Several attendees started trying Clojure out pretty much immediately and I expect to be helping them get up and running via IM, email and my blog, with posts like this: http://corfield.org/blog/post.cfm/getting-started-with-clojure (and several follow-ups where I've posed a small problem and offered solutions in Clojure and other languages). At work, I'm helping one of my colleagues come up to speed as we introduce Clojure into our production codebase which is mostly CFML with a little Scala. Over time I expect that to shift so most new code written in the model is Clojure, with CFML used for the view / controller portions (where that language really excels, IMO). I don't expect our use of Scala to grow much. It's also worth saying that there is a perfectly defensible position that says if you dumb down the documentation and offer too much hand-holding, you will get an influx of programmers whose skill level may lead to a lot of poor code that then gets Clojure a bad reputation as an unmaintainable, poorly performing language. Don't think it can happen? Look at Basic, CFML, PHP which all have a reputation for poorly structured code because of too many n00bs being able to pick them up easily and write bad code. Heck, even Java suffers from this to some extent! It has become so mass-market that pretty much any programmer can pick it up and churn out completely awful "OO" code. I've seen lots of terrible Java code written by less-than-average developers because Java is sufficiently newcomer-friendly. Perhaps it's inevitable as a language gets popular but maybe we should not rush to enable that happening in Clojure... :) -- Sean A Corfield -- (904) 302-SEAN An Architect's View -- http://corfield.org/ World Singles, LLC. -- http://worldsingles.com/ Railo Technologies, Inc. -- http://www.getrailo.com/ "Perfection is the enemy of the good." -- Gustave Flaubert, French realist novelist (1821-1880) -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
