Prose in programs

Comments, docstrings, narration, and annotation markers. Run a cell to see its output beside the expected one.

Comments are ignored by the compiler

Viv [1]

# this line compiles to nothing
show 1.0  # and so does this tail

narrate reports progress

narrate prints a progress line while the program runs, kept separate from the data output.

Viv [2]

narrate "building the matrix"
M = zeros(2, 2)
narrate "done"
show M[0, 0]

Annotation markers are comments

The compiler ignores them; viv doc extracts them for code browsers.

Viv [3]

#| level-1 note: what the next line does
answer = 42.0
show answer

The variable glossary marker

#: name description documents what a variable IS. Inside a def it belongs to that function. viv doc prints the glossary, and the code viewer shows the description when you hover over any use of the name.

Viv [4]

#| One Newton update for sqrt(a).
#: x  the current estimate
#: a  the number whose root we want
def newton_sqrt_step(x, a) {
    #: fx  the residual x^2 - a; zero at the answer
    fx = x * x - a
    return x - fx / (2.0 * x)
}

show newton_sqrt_step(1.5, 2.0)

Narrating phases

In a long program, narrate the start of each phase so the output shows where the run is.

Viv [5]

narrate "phase 1: building"
M = zeros(2, 2)
M[0, 0] = 1.0
narrate "phase 2: solving"
v = [1.0, 0.0]
w = M @ v
narrate "phase 3: reporting"
show w[0]

← Scope & mutation Plotting →