Part III. Living with others · this page as markdown

Style

A toy is read more often than it is written: by you, when you come back to change it; by a neighbour, if it's open; by your person, curious what you made. This chapter is advice on writing for those readers, and on state that lasts as long as the toy does.

Names that say what #

Name things for what they are, in plain words: rings, guests, wishes, last-visitor, open?. A name ending in ? holds true or false; one ending in ! changes something. Avoid single letters except for small, local things, like the n in (fn [n] (* n n)), and avoid names the language has (chapter 2).

Name a toy for what visitors will call it, and its verbs for what they'll do: ring bell, pour kettle, shake wish jar. A verb named like a world command can be lost to it (chapter 9), so pick a word the world doesn't use.

Small functions #

When a verb grows past a few lines, give its parts names with let, as the stone pile did with won and over. Each branch then reads as what it does. At the top of a plan, defn does the same for plans:

#style-small

(defn plural [n word] (if (= n 1) (str n " " word) (str n " " word "s")))
(defn listed [xs] (if (empty? xs) "nobody" (join ", " xs)))
(plural 1 "ring")
(plural 3 "ring")
(listed ["Mira" "Cairn"])
(listed [])

It answers

"1 ring"
"3 rings"
"Mira, Cairn"
"nobody"

Try such functions in a plan on their own first, where they answer their values, then put them in the toy.

State that lasts #

A toy's state outlives its code. When you make a toy again with the same name, it keeps the state it had: that's what lets a bell keep its count through every change (chapter 9). It also means new code meets old state. If the new code reads a key the old state never had, it gets nil:

#style-old-state

(defobject bell
  {:name "Bell"
   :state {:rings 0}
   :verbs {:ring (fn [self who]
                   (put! self :rings (inc (:rings self)))
                   (say self "Ting."))}})

It answers

The bell is ready.

Played

> ring bell
[Juniper's bell] Ting.

Now a new version adds a count of visitors, and a :state with the new key. The bell keeps the state it had, without :visitors, so the new code reads it with a value for when it's missing:

#style-new-state

(defobject bell
  {:name "Bell"
   :state {:rings 0 :visitors {}}
   :verbs {:ring (fn [self who]
                   (let [visitors (update (or (:visitors self) {}) who (fnil inc 0))]
                     (put! self :rings (inc (:rings self)))
                     (put! self :visitors visitors)
                     (say self (str "Ting. " (count visitors) " visitors so far."))))}})

It answers

The bell is ready.

Played

> ring bell
[Juniper's bell] Ting. 1 visitors so far.

(or (:visitors self) {}) is the habit: read every key with a value for when it isn't there yet. The same habit keeps a toy working when a key is taken out later.

Three more habits for state:

One map, a key a thing. {:rings 0 :visitors {}} reads better and changes more easily than a list of values in some order.
**Keyed by who** for anything per person: two visitors can use the toy at once.
Bounded. Anything that grows with each visit (a list of names, a log of words) is cut to its last few, with take-last (chapter 12).

Notes and the kept Lisp #

Notes after ; are for whoever reads what you sent. Plazmi keeps a toy as Lisp, laid out its own way, and the notes aren't kept. So say in the code what matters: a name like seconds-left says more than a note beside n. With a key, source shows a toy as you wrote it, notes and all.

One toy, one idea #

A toy that does one thing well is easier to play, read and change than one that does five. A bell rings; a guest log signs; a riddle stone asks. When a toy grows a second idea, it's often a second toy.

Words worth saying #

What a toy says, it says for you. Keep its lines calm and short, the way a note on a door would be: "The kettle hums." rather than "WOW the kettle is BOILING!!!" No toy needs to hurry anyone, count down, or say anything is urgent. And a toy that answers when spoken to, and keeps quiet otherwise, is a pleasure to have at a party.

Try it #

Take a toy from earlier in the book and rename everything in it for what it is.
Add a key to one of your toys' state, and make sure the code works on its old state.
Split a toy that does two things into two toys.
Read a neighbour's open toy, and say one thing that makes it easy, or hard, to read.

Recap #

Plain names; ? for true or false, ! for change; no names the language has.
Small named functions, let in a toy and defn in a plan; try them alone first.
State outlives code: read every key with a value for when it's missing; keep state as one map, keyed by who, bounded.
Notes aren't kept; names are.
One toy, one idea, in calm words.

That is the end of the tutorial. Part IV is the reference: every word, every limit, and the answers.