{
  "id": 528057,
  "title": "Write down every guarantee before you write any code",
  "url": "https://urgent.news/2026/08/11/write-down-every-guarantee-before-you-write-any-code",
  "topic": "culture",
  "section": "Culture",
  "published": "2026-08-11T03:35:29.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/copyleftdev/write-down-every-guarantee-before-you-write-any-code-21oi"
  },
  "original_language": "en",
  "account": "Here is a summary of the story:\n\nEvery promise a to-do list makes includes the following guarantees: tasks cannot go directly from absent to done; opening, completing, reopening, deleting and clearing completed items must be done one at a time; and ClearCompleted only works when there are done items to clear. These nine lines of guarantees constitute the complete contract for a to-do list system, but they are not explicitly documented anywhere. Instead, the guarantees are embedded in a test suite that asserts outcomes, scattered validation, and the memory of senior developers. The author argues that understanding and documenting these guarantees upfront can catch bugs before any code is written, saving time and effort. The article then explains the rules used in the TLA+ specification language to formally define the to-do list behavior. The key operators define how tasks transition between states and how the Next action can change the state of the system. The Spec line ties the initial state and all possible next state transitions together. The article concludes by noting that while a real to-do list system's guarantees are likely much longer and more complex, the core principles remain the same - write down and enforce the essential guarantees early in the design process.",
  "summary": "Here is every promise a to-do list makes. VARIABLE tasks Init == tasks = [i \\in Ids |-> \"absent\"] Add(i) == tasks[i] = \"absent\" /\\ tasks' = [tasks EXCEPT ![i] = \"open\"] Complete(i) == tasks[i] = \"open\" /\\ tasks' = [tasks EXCEPT ![i] = \"done\"] Reopen(i) == tasks[i] = \"done\" /\\ tasks' = [tasks EXCEPT ![i] = \"open\"] Delete(i) == tasks[i] # \"absent\" /\\ tasks' = [tasks EXCEPT ![i] = \"absent\"]…",
  "key_points": [
    "Nine guarantees define behavior of to-do list system",
    "Guarantees embedded in test suite, not documented",
    "Documenting guarantees early can prevent bugs"
  ],
  "editors_take": "Documenting guarantees upfront for a system like a to-do list allows developers to catch bugs before coding, saving time and effort by clarifying essential behavior and state transitions.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}