Danger markers

The idea

In most languages, a function call that writes a file looks the same as one that adds two numbers. The reader has no way to tell without reading documentation or tracing the entire call chain. Vision makes this visible at the call site.

Every line that reaches outside the program — disk, network, clock, environment, standard output — is prefixed with >>. Every line that performs an action that cannot be undone is additionally marked with !!.

The compiler enforces these markers. A side-effecting operation without >> is a compile error. The reader never has to guess.

The >> marker

>> marks a line that touches the world: writes to a file, reads the clock, sends a network request, writes to standard output. Any interaction with something outside the running program.

// calm lines — no markers, provably side-effect-free:
the total is the price plus the tax
for each item in the items
    add item to the tally

// dangerous lines — marked >>:
>> write the tally to the file at the path
>> say the total

A line without >> is provably calm — it does not reach outside the program. A reader can skip over calm lines when looking for the places that affect state they care about.

The !! marker

!! additionally marks a line that cannot be undone. It always appears alongside >>. The classic example is deleting a file:

// can't be undone — marked >> !!:
>> !! remove the file at the path

The visual weight of >> !! is deliberate. A line that destroys data permanently should not read as gently as the line before it.

Atomic patterns

The >> marker makes structured patterns immediately readable. The classic atomic write — write to temp, fsync, rename — is visually distinct from the pure logic around it:

to save the note, given the words and the path:
    the temp path is "{the path}.tmp"
    >> write the words to the file at the temp path
    >> make sure the file at the temp path is saved
    >> rename the file at the temp path to the path

A reader who sees three consecutive >> lines knows: this is the durable-write section. They can find it at a glance across any length of code.

Why it matters

Side effects are the source of most software bugs that are hard to reproduce: files left in a wrong state, network calls that happened once but shouldn't have, clocks read at the wrong time. Making side effects visible at the call site lets a reader — and a reviewer — see at a glance where the world is being touched.

No mainstream language requires this. Vision does. It is not a convention or a linter rule; it is enforced by the compiler. You cannot accidentally write a side-effecting operation and leave it unmarked.