Programming notes that explain more than the code

Start with the question you were trying to answer

A folder full of snippets can be difficult to use because the original problem has disappeared. Name the node after the question: “How do I calculate a mean safely?” or “Why is this queue operation slow?” Then keep the language and relevant version in the note.

This makes the map a record of reasoning rather than a second source-code repository. Keep the working project in version control and link to the relevant file or documentation where appropriate.

Keep the example small enough to inspect

Here is a JavaScript example for a non-empty array of finite numbers:

function mean(values) {
  if (values.length === 0) {
    throw new Error("Expected at least one value");
  }
  return values.reduce((sum, value) => sum + value, 0)
    / values.length;
}

The important note is not only the snippet. Record its assumptions: it expects an array; its elements are finite numbers; it does not handle arbitrary text input; and normal JavaScript floating-point limits apply. Input validation would be a separate concern in an application.

Add a test checklist: [2, 4, 9] should give 5; [7] should give 7; an empty array should throw. Run those tests in your programming environment. The code in a note is for reading, not execution.

Connect the snippet to a concept

Put the example under a branch such as “Aggregating a sequence.” Add neighboring nodes for the initial accumulator value, division by the count, and the empty-input case. Now the map shows what the code is doing rather than merely displaying a large block of syntax.

In Mappy, code blocks and longer explanations can live inside expanded notes. You can also use formulas when the mathematical definition is clearer than the implementation. Keep short labels on the canvas so the example remains easy to navigate.

Write the mistake you would otherwise repeat

After debugging, add a brief “What went wrong” paragraph. Was the assumption incorrect, the input different, or the API misunderstood? Save the corrected explanation alongside the example and a link to the official reference you used.

Do not put API keys, passwords, or private production data into study examples. A minimal invented input usually explains the behavior more clearly and is safer to share. Review your notes before exporting them to another person.