Reading a schematic

Try it on a pull request

A schematic draws one function. Read it from the top. When the function splits, read across.

The line at the top names that function and lists its parameters. In the picture below, saveDraft(note) is the function being drawn.

Sequence

Plain statements stack, in the order they run. A run of them shares one block.

saveDraft(note)

const title = note.title.trim()

const body = note.body.trim()

store.set(note.id, { title, body })

Guards

A guard is a check that leaves at once. It takes a single row: the condition, an arrow, and the exit. A ladder of guards stays flat.

loadUser(id)

returns early if !id→ return null

returns early if !known(id)→ return null

returns return fetchUser(id)

If and else

The two paths sit side by side, so you can compare them in one glance.

reply(ready)

if ready

accept()

else

hold()

Switch

Each case is its own row. The label is on the left and the work is on the right.

label(status)

switch status · 3 cases

'open'

returns return 'Open'

'closed'

returns return 'Closed'

default

returns return 'Unknown'

Loops

A violet bar marks a loop. When the loop walks a collection, everything to its right runs once per item. A while or an unbounded for is the same bar; the header says which.

sendEach(messages)

repeats loop for each message of messages

send(message)

Try and catch

try is a gray bar. catch is a red bar beneath it, with its own block for the failure.

readConfig(path)

try

returns return parse(load(path))

catch err

report(err)

returns return null

Callbacks

A callback is a dashed frame, and it has its own scope. A return inside the frame leaves the callback, and its arrow stops at the frame. The outer return is the one that reaches the exit rail.

publish(order)

an inner function callback (item) passed to queue.add()

returns early if !item.id→ return

notify(item)

returns return order.id

Databases and requests

A row carries a tag only when its text matches a SQL statement or an HTTP call the front end recognizes. A read is teal, a write is amber, and a request is blue. The tag names the table or the request. A call that is not recognized has no tag, which means the front end did not see one, not that the function does no IO.

async record(order)

SELECT orders await db.query('SELECT id FROM orders')

INSERT audit await db.query('INSERT INTO audit')

POST /paid await fetch('/paid', { method: 'POST' })

The exit rail

Every return and throw that leaves the function runs out to one rail on the right. When the function can also fall off the end, that path is marked end.

settle(invoice)

returns early if !invoice→ return null

leaves by an exception if invoice.void→ throw Error: void

charge(invoice)

end falls off the end

Nesting

Fill warms as blocks nest. Calm code stays narrow and cool. Deeply nested code draws wide and warm.

The first chip in the header is the measured cognitive complexity. Green runs up to 5, amber up to 15, and red above that. charge scores 6, so its chip is amber. The color makes a high number easy to see. It is not a claim that the function is wrong.

charge(user, order, card)

cognitive 6cyclomatic 4nesting 3exits 09 lines

if user

if order

if card

bill(order)

A diff

An added row carries a + and a removed row carries a −. Green is added and red is removed, and the mark stays with the row.

price(order)

returns early if !order→ return null

returns removed −return order.total

returns early added +if order.comp→ return 0

returns added +return tax(order.total)

How much detail

The front page and the app draw a function at five levels, listed here from least to most detail. Headers shows only the header; each step after it adds one kind of information, down to the code itself. The + button (or the + key) zooms in toward the code, and − zooms out toward the headers. Changing level keeps the line you were reading in the same place on the screen, until you scroll. The app opens a pull request at Schematic and a repository, folder or file at Headers.

Level	What it shows	The question it answers
Headers	Only each function’s header: name, parameters, complexity. Click one to open it.	What is in this file, and what does each function promise?
Outline	Decisions and exits in words. Runs of statements are plain bars.	What does it decide, and where can it leave?
Schematic	Every step in plain words, without comments and logs.	What does it do, step by step, in plain words?
Denoised	The function’s code, with comments, docstrings and logs faded.	The code without comments, docstrings and logs
Full	The function’s code, as written.	The code exactly as written

Outline keeps the blocks and folds a run of statements into one bar. Schematic writes every step out in words.

Outline

sendEach(messages)

repeats loop each message in messages

Schematic

sendEach(messages)

repeats loop for each message of messages

send(message)

Try it on a pull request