Writing a beginner-friendly REPL guide for clojure.org, please send me inspiration


#1

My priority is to help beginners get proficient enough at the REPL that they find it rewarding, then give them opportunities to dig deeper - a bit like when learning a musical instrument.

I’m sure a lot of great material already exists, scattered over the Web - please send me links! Here are some examples of helpful resources:

You can also help by answering those questions:

  • What are the big “AHA” moments of a REPL beginner? What resources or experiences inspired them?
  • What are the big hurdles in learning how to use the REPL?

#2

@plexusThe Bare Minimum captures many of my thoughts.

How much do you intend to get into REPL-adjacent tooling? Paredit would be quite a detour, as are other semantic-editing features like sexp-aware text selection. Your contribution in the workflow thread suggested heavy use of state management libs, which would be another major detour.

One lesson of the workflow thread is that REPL usage varies enormously from person to person: what devs want from it, how they interact with it, which one they use. That leads me to believe that individual-REPL-specific guides (e.g. CIDER-specific, inferior-lisp-mode-specific…) are one extremely promising direction for the community to create documentation. It will be interesting to see what commonalities can be found across REPLs for a generic REPL guide. Perhaps walking people through the bare command-line REPL available from clj would be ideal, even though it’s far from most people’s eventual workflow and lacks many interface affordances. You could, as you suggest, then point readers to specific REPLs that require more setup in exchange for features.


#3

How much do you intend to get into REPL-adjacent tooling?

Nothing more than providing links to such tools, without any preference expressed, trying to be exhaustive and to summarize briefly the problems they address.

I am well aware that there is no objectively best dev setup and that people’s taste vary greatly in this area (I can tell, I tried using Emacs 6 times and failed), so I’ll try to remain very generic and neutral.

It will be interesting to see what commonalities can be found across REPLs for a generic REPL guide.

In this regard, I intend to write an “what to expect from editor integrations” section, examples:

  • load current buffer in REPL
  • switch REPL namespace to current buffer
  • send form before / surrounding caret to REPL

For each of these, I’ll describe what it mechanically translates to using a bare command-line REPL and an open editor.

I will also add links to common REPL libraries (tools.trace, Sayid, spy-scope, scope-capture etc.): I’ll also add a brief description of what problem they address.

Finally, I’ll add a ‘community resources’, with links to various articles, talks and screencasts with a synopsis for each.

Perhaps walking people through the bare command-line REPL available from clj would be ideal, even though it’s far from most people’s eventual workflow and lacks many interface affordances.

It does lack many affordances, but I also think it’s useful to start with a ‘bare minimum’ CLI REPL, to get an understanding of how the more integrated tools work behind the scenes.

To summarize: I don’t want to get into the (opiniated) rabbit hole of ‘advanced workflows’ - I’d rather equip the reader with enough background that she can do that herself, and also talk a bit of the ‘architectural’ challenges that arise from REPL-based development (making code REPL-friendly etc.).

@dave.liepmann but hey, don’t take my word for it :slight_smile: are you interested in giving me feedback on the draft?


#4

Got some ideas this morning. I just thought there are too few step by step guides in Clojure community. I was from JavaScript community, when Node.js was spreading, when React was spreading, when Vue was spreading, I saw many step by step guides helping beginner to learn.

To beginners, concepts and terms are sometimes useless, because they(I mean what I was) can’t absorb those concepts you concluded after programming so much. Only skill they have is watching how tools work and remember that in mind with their own languages. And they may need months or years to understand all the concepts, but remembering how each piece code running is way easier.


#5

The more we can do to get the message out about how important the REPL-focused workflow is, the better!

I didn’t get productive with Clojure until I got to the point where I could hot-key-evaluate code as I typed it in and stopped thinking about the REPL being a “separate process” rather than an integral part of how I developed code…


#6

Sure, send it to my username at gmail. It’ll be an extremely async process :slight_smile:


#7

+100 to that. Most of what he have online currently is ‘reference’ material - which is fine in itself, but using that as teaching material for beginners is a bit like teaching kindergarteners how to count by constructing mathematical logic then set theory then number theory in front of them.

This guide will be very much step by step. The target audience will be beginners with nothing more than a basic understanding of Clojure (say, syntax and functions), who know how to open a terminal window.

So my priorities are (most important first):

  • getting a basic set up
  • getting comfortable with the REPL
  • motivating and demo-ing the use of the REPL for everyday development
  • identifying and preventing common pitfalls (error messages etc.)
  • raising awareness about the challenges of REPL based development (keeping the REPL and source code in sync, reloadable architectures, state management etc.) - without necessarily digging deep into the solutions
  • making it easy to discover the more ‘advanced’ ways to increase their mastery of the REPL (pro tips, blog posts / screencasts / talks, editor integrations / advanced REPL clients and what to expect of them, etc.)

New notions (such as namespaces and libs) will be introduced one by one, with as few prerequisites as possible, with approximations when necessary, redundantly if that helps, and always with examples.


#8

Big agree here. Refuting the “grammar reference book” style of introducing people to programming languages was a big motivator behind maria.cloud.


#9

First draft: https://5a9d2be7be40f13a7f060a2c–clojure-site-preview-vvvvalvalval.netlify.com/guides/programming_at_the_repl.html

Feedback is more than welcome, at any level!

When giving feedback, it helps me if you state your level of experience with Clojure, as well as your expectations for such a guide.

EDIT: fixed the link.


#10

The big AHA for me was:
A. paredit
B. then:

  1. (slurp file of table) => long string
  2. wrap in read-line => coll of lines
  3. wrap in string-split #“whitespace” => coll of coll of cells
  4. now start wrapping that in map/reduce/filter commands to work on the cells
    Now being able to twiddle the map/reduce/filter commands until I get it right.

For that wrapping paredit was a revelation because when wrapping I need to an a paren at the very beginning and one at the end. The two get further away with every iteration. So paren slurp and paren spit were part of the experience.

The slow AHA from paredit is that my brain swiched from thinking the code as string to thinking the code as nested fns or a tree of fns.

C. pasting Data from spreadsheets into the repl
e.g for the udacity class on statistics. They link to a google sheet. They tell students to mark a column and use spreadsheet functions. But I can type at the repl:

  1. (def data {})
  2. Then in google sheet or excel I put the cursor on the first item of two columns spreadsheet. I use keys to mark two colums and ctrl-a or something to mark the whole columns.
  3. Then I ctrl-c copy the excel columns.
  4. Paste the data into the empty map of line 1. (def data {paste here})
  5. Hit return and data contains the excel statistics data.
  6. Continue on a similar path as with the slurp above to first clean, then explore the data.

#11

This is really top notch. A lot of work has gone into