Designing a Program with Subroutines

Suppose you have been asked to write a program that opens a window, fills it with colors, and then keeps changing squares in that window. You already know roughly what the program should do, but you do not yet know how each piece will be coded. A natural first move is to write the plan down as a short list of big steps. The author of the source example did exactly this: open a Mosaic window, fill the window with random colors, and then move around changing squares at random.

That list is a legitimate algorithm, but it is far too vague to turn directly into code. Phrases like move around changing squares at random hide many decisions: where to start, how to choose the next square, and when to stop. This article follows the process of making such a plan precise enough to implement, and then looks at how the program keeps track of where it is while it runs.

Instead of coding the vague version, you keep examining each step and asking whether it can be described more precisely. Each pass produces a slightly more detailed algorithm. You do not have to decide everything at once. This repeated, gradual elaboration is the heart of stepwise refinement, and it is what makes a large task manageable: a big task that is hard to hold in your head becomes a set of smaller tasks you can work on one at a time.

The mosaic author refined the vague third step by expanding it. The program starts in the middle of the window and then repeatedly moves to new squares and changes their colors, for as long as the window remains open. The expansion adds two things the vague version lacked: a starting condition and a stopping condition. A refined loop usually needs explicit starting and stopping conditions like these before it can be coded.

Read the diagram from the top down. The top node is the whole program, and each level below it is a more detailed description of the level above. The starting position and the loop are refinements of the vague third step. In the source they are not separate subroutines; they are steps that the refinement makes precise.

Not every step in a refined outline should be pulled out into its own piece. The useful question is whether a step describes a coherent task that can be handled on its own. In the mosaic example, filling the window with random colors is a clear, self-contained job. It does not depend on how the program will later move around the window, so it can be worked on separately. The author therefore writes a separate subroutine for it.

A subroutine is a separate block of code that carries out a specific task. Because it is a unit of its own, the main routine can call it by name at the point where that task is needed. The source gives the reason the mosaic author pulls tasks out: using subroutines makes the main routine simpler and easier to understand.

The source already has one subroutine available, Mosaic.open(), which opens the window. The author then decides to write two more subroutines to carry out the two tasks inside the while loop. The refined algorithm reads as a short sequence of calls, and each detail lives inside the subroutine responsible for it.

A loop that moves around a window needs a record of its location. The author represents the current position with two int variables. The variable currentRow holds the row number of the square where the disturbance is currently located, and currentColumn holds the column number. A variable holding information like this, which describes what the program is doing at a given moment, is one way of representing program state.

The mosaic has 16 rows and 20 columns of squares. Placing the current position in the center therefore means setting currentRow to 8 and currentColumn to 10. These two values are the state the loop depends on. Each time the loop moves the current position, these values are the things that must change.

Read the diagram from left to right. Each pass starts from the values left by the pass before it. If you want to know where the disturbance is at any point, you look at the two variables, not at the loop's code. This is why the values of this state are the first place to check when a result differs from what was expected.

Suppose the refined algorithm is correct on paper but the program changes the wrong square. The fastest way to find the fault is to walk through the refined steps in order and compare the state at each step with what was intended. The first step where the recorded state disagrees with the plan is where the path departs from the intended behavior.

Consider the mosaic example. If the start was supposed to be the center, the intended state is currentRow = 8 and currentColumn = 10. If, while tracing, the values after the start step show something else, the error lies in the start step or in how the variables were set there. The loop's body may look correct when read by itself, but the source warns that if the position variables are wrong, the program changes the color of the wrong square even when every line of the loop looks right.

Imagine a program that needs the same job done in three different places. You could copy the same lines of code three times, or you could write those lines once and let the rest of the program use them whenever they are needed. A subroutine is the second option. Writing it once lets the program reuse it at many points.

The important word is called. A subroutine does not run just because it exists in a program. It runs when the program reaches a point where it calls it. Because the same block can be called more than once, a single piece of code can serve many moments in a single run of the program.

When the main program reaches a call, control jumps into the subroutine, the subroutine's instructions run, and then control returns to the main program at the point after the call. The main program can then reach another call to the same subroutine later in the run. The diagram below shows one main program calling the same subroutine three times. The three calls are illustrative, written for this article to show the pattern.

The pseudocode above is an illustration of the mosaic structure described in the source, not the source's own code. Notice that the change-square code is written once but runs on every pass. The main routine stays short because each detail is delegated to a named subroutine.

The source points to a concrete program that uses subroutines: ThreeN2.java. It is introduced in Section 4.4 as an improved version of the 3N+1 program, and the source describes it as a program that uses subroutines and prints its output in neat columns. This is the source's own example, so it is a good place to see the idea in an actual program.

The source gives two reasons ThreeN2.java relies on subroutines. The first is code organization: separating work into named blocks makes the program easier to read and manage. The second is output formatting: the program prints its results in neat columns, and the subroutines are part of how that formatting is achieved.

The source does not list the individual subroutines inside ThreeN2.java or show their code, so this article does not describe them in detail. When you open the file yourself, look for the places where the program calls a named block of code, and compare them with the places where it prints results.