Why draw at all
A grid program is already a picture, but it is a picture made of instruction characters, not of routes. The characters tell you what each cell does, and you have to infer the path in your head. A separate drawing of the route reverses the emphasis: it shows where the pointer goes, and leaves the instruction details as small labels. For anyone planning a program or explaining one, this is often the clearest view.
Flow diagrams are not a new idea. Ordinary programmers have long drawn boxes and arrows to explain code. The difference here is that, in a grid language, the diagram can be nearly identical to the program, because the program’s structure is already spatial.
Start with a sketch on squared paper
Squared paper (or any editor that shows a monospace grid) works well because each square is one cell. A simple process for planning a program:
- Write the task in one sentence, and list the values you need to keep.
- Draw the main route as a line of arrows, starting from the top-left corner heading right.
- Mark the places where the route must decide something and draw each outcome as a separate line leaving that square.
- Decide where branches rejoin, and where any loop returns.
- Only then replace each arrow square with the real instruction and fill the squares in between with the work to be done.
Drawing before typing also makes later grid debugging easier, and it keeps you from making a layout that is tangled when a simple one was available. Moving a line on paper costs nothing, while moving a line in a finished grid can break several crossings.
What to mark on the diagram
A good flow sketch has a few consistent marks.
- Direction arrows along each leg of the route, so that a reader never has to guess which way the pointer travels.
- Decision squares drawn differently, for instance circled, with the outcome of each exit labeled (zero or nonzero, for example).
- Loop-back lines drawn in a second color so that repeated segments stand out from straight-through ones.
- Data squares shaded, to show cells that hold values and should never be entered, which links to the ideas in the dead code article.
- Stack notes beside key points, such as “top is the counter here”. These are a short list, not a full trace.
Colors are optional. If you only have one pen, dashed lines for loop-backs and boxes for decisions are enough.
An example of reading a path from a picture
Consider a loop that prints a countdown from five. As a route sketch, you would draw a short line along the top row, with a step that prints and subtracts, then a turn downward into a decision square, then a long line back to the left and up to the start of the loop, and a short exit to the right that leads to an end marker. Without any instruction characters, a viewer sees “a ring with one exit”. Adding the instructions comes afterward and is mostly a matter of fitting characters along the route.
The ring shape here is the same idea as the geometric loops discussed elsewhere in this cluster, and a sketch makes it easy to see that the exit comes off a single decision square. The finished program resembles the countdown program example in the techniques section.
Drawing to check a program that already exists
You can also draw in the other direction. Take a program someone else wrote and trace its route with a pencil on a printout, one leg at a time, without caring what the instructions compute. After a few minutes, the structure usually appears: which regions are ring-shaped, which squares branch, and which parts are never touched. Then mark the stack changes. This is a lighter relative of tracing by hand, which follows every value, and it is a good first pass before the detailed one.
If the sketch ends up with lines crossing in a way you did not plan, that is a sign. Crossing is allowed in most grid languages, as the pointer can travel straight over the crossing, but it is also the place where mistakes happen, so those squares deserve extra attention.
Digital tools
A drawing does not need to be on paper. A plain text editor in a monospace font lets you draw routes with ordinary characters such as dashes and bars, and then later overwrite them with real instructions. A small program that records each cell the pointer visits and draws the result is the idea behind a trace visualizer, which is the automated version of the pencil route. Seeing a route lit up on screen while a program runs is a good way to compare what you planned with what really happens.
Keeping diagrams as documentation
Hand sketches often outlive the code they came from, and that is a good reason to keep them tidy. Good code layout and a flow sketch that sits next to the program serve together as the missing legend for a very hard-to-skim format. A few habits help:
- Use the same coordinates on the sketch and the program, such as numbering columns across the top and rows down the side.
- Mark the start square and every exit.
- Note which cells hold data.
- Update the drawing after every layout change, or delete it; an out-of-date drawing is worse than none.
A path drawing will not catch every bug, since it hides the values flowing along the lines. It does, however, make the shape of a program visible, which is usually the hardest thing to see in a block of characters.