Date: 2026-07-06
This glossary explains Hum words for people who do not already think like programmers.
Hum should not make beginners memorize mystery words before they can build something. Each term should answer a normal human question.
A Hum program is made of promises.
A task says what it is trying to do, what it uses, what it changes, what must
be true before it runs, what it promises after it runs, and the exact steps it
takes.
A program is the whole thing you are building.
Example: a task list, a game, a server, a compiler.
A module is a named section of a program.
Beginner phrase:
This file belongs to this part of the program.
Hum:
module examples.task_list
A type describes what a thing is made of.
Beginner phrase:
A task has a title and a done flag.
Hum:
type Task {
title: Text
done: Bool
}
A field is one named piece inside a type.
In this type, title and done are fields:
type Task {
title: Text
done: Bool
}
A value is an actual piece of data.
Examples:
"buy milk"false42- a
Task
let gives a name to a value that will not change.
Beginner phrase:
Remember this value under this name, and do not change it.
Hum:
let title: Text = "buy milk"
change gives a name to a value that may change.
Beginner phrase:
This value is allowed to change in this task.
Hum:
change attempts: UInt = 0
set changes a value that was already declared with change, or a value the
task is allowed to mutate.
Hum:
set attempts = attempts + 1
A task is an action the program can perform.
Beginner phrase:
This is something the program knows how to do.
Hum:
task add task(title: Text) -> Result Task, TaskError {
why:
let the user remember something to do
does:
create task
}
A parameter is information a task needs from the caller.
In this task, title is a parameter:
task add task(title: Text) {
does:
use title
}
A result is what a task gives back.
Hum:
task add task(title: Text) -> Result Task, TaskError
Beginner phrase:
This task either gives back a Task or fails with a TaskError.
A store is program memory with a purpose.
Use it instead of casual global variables.
Beginner phrase:
This is where the program remembers something important.
Hum:
store tasks: List Task {
why:
remember the user's tasks
}
why: says why code exists.
Hum:
why:
let the user remember something to do
If the why: is not clear, the code probably is not ready.
uses: lists outside things a task reads or depends on.
Hum:
uses:
clock.now
random.secure
sessions
Beginner phrase:
This task looks at or depends on these things.
changes: lists outside things a task is allowed to modify.
Hum:
changes:
sessions
Beginner phrase:
This task is allowed to change sessions.
If a task changes something but does not list it here, the compiler should stop it.
needs: says what must be true before a task runs.
Hum:
needs:
title is not empty
Beginner phrase:
Do not run this task unless this is true first.
ensures: says what must be true after a task succeeds.
Hum:
ensures:
new task is saved
new task is not done
Beginner phrase:
If this task works, these things must be true afterward.
fails when: lists expected ways the task can fail.
Hum:
fails when:
title is empty
Beginner phrase:
This is not a crash. This is a known failure case.
watch for: lists edge cases that deserve attention.
Hum:
watch for:
title may be only spaces
Beginner phrase:
This is the kind of future bug we are worried about.
protects: says what security or safety promise this task defends.
Hum:
protects:
session token cannot be guessed
Beginner phrase:
This task helps keep this thing safe.
trusts: says what assumption the task depends on.
Hum:
trusts:
random.secure is cryptographically strong
Beginner phrase:
This must be true, but this task does not prove it by itself.
cost: says how much work or memory the task should use.
Hum:
cost:
time: O(tasks)
space: O(1)
allocates: nothing
check: warn
Beginner phrase:
This tells readers and tools how expensive the task is expected to be.
allocates: says what new memory the task creates.
Hum:
allocates:
one task
Beginner phrase:
This task creates this much new memory.
avoids: says what the code is intentionally not doing.
Hum:
avoids:
network call inside loop
Beginner phrase:
Do not change this code in a way that does this bad thing.
tradeoffs: explains a decision that has costs and benefits.
Hum:
tradeoffs:
linear display is expected because every visible task must be shown
Beginner phrase:
We chose this path for this reason, even though another path exists.
does: contains the exact steps of the task.
Hum:
does:
if title is empty {
fail TaskError.empty_title
}
save task in tasks
return task
Beginner phrase:
This is what actually happens.
if means choose based on a condition.
Hum:
if task.done {
show task as completed
} else {
show task as active
}
for each repeats something for every item in a collection.
Hum:
for each task in tasks {
show task
}
while repeats while something is true.
Hum should prefer visible bounds when possible:
while attempts < 16 {
set attempts = attempts + 1
}
match handles each possible case of a value.
Hum:
match result {
ok task:
show task
error reason:
show reason
}
Beginner phrase:
For each possible shape this value can have, say what to do.
A test checks that code behaves as promised.
Hum:
test add task rejects empty title {
does:
expect add task("") fails with TaskError.empty_title
}
Beginner phrase:
This proves one promise still works.
A regression test protects against a bug that happened before.
Hum:
test empty title with spaces is rejected regression {
regression:
found when title " " was accepted as nonempty
}
Beginner phrase:
This bug happened once. Do not let it come back.
private means only this part of the program can use it.
Hum:
private store sessions: Map SessionId -> Session
export means other parts of the program are allowed to use it.
Hum:
export task create session(user: User) -> SessionToken
package means usable inside the package, but not public to everyone.
Hum:
package task rotate token(session: Session)
unsafe means the compiler cannot fully prove the operation is safe by itself.
Unsafe code must explain its reason and promises.
Beginner phrase:
This is powerful code. It needs extra proof and review.
If a beginner asks, "where does this happen?", Hum should point to one of these blocks:
why:for purposeuses:for what it readschanges:for what it mutatesneeds:for beforeensures:for afterfails when:for known failurewatch for:for edge casesprotects:for securitytrusts:for assumptionscost:for performancedoes:for steps