# Style

From A Little Lisp for a Small World, the Plazmi Lisp book (https://plazmi.gg/book). Checked against Plazmi Lisp version 2, 12 November 2026. The whole book as one file: https://plazmi.gg/book.md

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:

```clojure
(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 [])
```

```text
"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`:

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

```text
The bell is ready.
```

```text
> 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:

```clojure
(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."))))}})
```

```text
The bell is ready.
```

```text
> 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

1. Take a toy from earlier in the book and rename everything in it for what it is.
2. Add a key to one of your toys' state, and make sure the code works on its old state.
3. Split a toy that does two things into two toys.
4. 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.


---

Before: [Limits, errors and refusals](https://plazmi.gg/book/limits-and-errors.md). Next: [The word table](https://plazmi.gg/book/reference.md). Contents: https://plazmi.gg/book.md