Subroutine Design

Imagine a window filled with a grid of colored rectangles. The colors keep changing while a small cursor wanders from one rectangle to the next. Now imagine the result looks wrong. Where do you start looking? This article answers that question using a mosaic animation program as a case study. The program is short, but it already contains the habit that matters most in program design: the main part of the program is written first, and the parts it depends on are described and written afterward.

The key idea is that a program is easier to understand when you separate two questions. The first question is when something happens. The second question is what that something accomplishes. The main routine answers the first question, and each subroutine answers the second.

A main routine handles the overall flow of a program and hands specific work to subroutines. In the mosaic program, the main routine opens the window, decides where the animation begins, and repeats the core action until the user closes the window. It does not hold every detail of how colors are chosen or how the cursor moves. Those details are pushed into separate pieces. A subroutine is a separate, small task, and the main routine is the only place that decides when each subroutine runs.

Read the sequence as a series of hand-offs. Control leaves the main routine at a call, runs through the subroutine's own steps, and then returns to the main routine at the point just after the call. The fill subroutine is called once at the start, so its arrow appears only once. The change subroutine is used inside the loop, so it is called again on every pass. Notice that to follow this flow you did not need to read how the color is chosen. The position of each call in the main routine is enough to answer questions about order.

The author has a main routine but not yet a complete program, because three subroutines are still missing: fillWithRandomColors(), changeToRandomColor(int,int), and randomMove(). The first is called once at the start, while the other two are used inside the loop. The hierarchy below shows how these pieces sit under the main routine.

The source names the three subroutines and tells you when each one runs. It does not give the full definition of changeToRandomColor(int,int) or randomMove() in this excerpt, so this article does not claim how they are implemented. From the name and the case study, changeToRandomColor(int,int) takes two integer arguments and is responsible for changing a color, and randomMove() is responsible for the cursor's wandering. Those roles are the ones to keep in mind when you later decide which routine owns a given behavior.

The source describes fillWithRandomColors() by its postcondition: each of the rectangles in the mosaic has been changed to a random color. Notice what this sentence leaves out. It says nothing about loops, indexes, or the order in which rectangles are visited. Those are algorithm questions, and they come later.

Once the postcondition is clear, the author writes pseudocode, an informal description of an algorithm that accomplishes the task. Pseudocode is not tied to any one language, so it lets you check the logic of a subroutine before translating it into code. The source gives pseudocode for fillWithRandomColors(), and the same approach applies to the other two subroutines. The order matters: postcondition first, then algorithm, then code.

After running the completed program, the author made one small change. To prevent the animation from running too fast, a delay call was added inside the while loop. The statement is Mosaic.delay(10), which takes an integer argument. Because the call sits in the loop body, it runs once per pass, so the pause applies to every step of the animation rather than only once at startup.

Suppose the finished mosaic shows a rectangle that keeps its old color after the initial fill, even though every other rectangle changed. The question is not what is wrong with the whole program. The better question is which routine owns the step that should have changed that rectangle. Starting from the postcondition makes the search concrete. The fill subroutine is defined as leaving every rectangle changed to a random color, so a leftover old color points at that subroutine's result rather than at the main routine's loop.