Designing Black-Box Interfaces for Subroutines

Once you start writing subroutines, a practical question comes up quickly: when code inside a subroutine works with a name, whose name is it, and who else is allowed to see it? Many beginners assume that every name inside a subroutine is connected to the rest of the program in the same way. That assumption leads to predictable surprises. This article sorts out which names a subroutine can reach, which of those names can influence the caller, and why the answer depends on where a name was originally declared.

A subroutine is a block of code that can be called multiple times from different parts of a program. Inside that block, the code can work with three different kinds of variables. The first is a local variable, which the subroutine declares for its own use. The second is a formal parameter, which is the name in the subroutine's header that receives a value from whoever calls it. The third is a variable declared outside the subroutine, which the subroutine can still reach. The source material calls this third kind a static member variable declared outside the subroutine. These three categories differ in where their names come from and in how far their effects travel.

The diagram shows the main sources of names a subroutine can use. Parameters and locals are both created for the subroutine, while the outer variables already existed before the subroutine ran. That single difference, whether a name belongs to the subroutine or to the wider program, explains most of the behavior discussed in the rest of this article.

A formal parameter is the point where a value enters a subroutine. When the subroutine is called, the caller's value is copied into the parameter name, and from then on the subroutine works with that name. The source puts it this way: once execution of the subroutine begins, a parameter behaves much like a local variable. The parameter name is a fresh name inside the subroutine, even though it started with a value supplied by the caller. Picture the caller and the subroutine as two separate boxes, each with its own labeled storage. The value moves across when the call happens, but the two labels still belong to different boxes.

For primitive types, a change made to the formal parameter inside the subroutine has no effect on the rest of the program. The caller's variable keeps whatever value it had before the call. The source adds a qualification: the situation is more complicated for arrays and objects, which it promises to treat later. This section limits itself to primitive types, where the rule holds cleanly. The following program is an original illustration of the rule, not code from the source.

A variable defined outside a subroutine is treated differently from a parameter. It is called global to the subroutine. It can be used throughout the class in which it is defined and, if it is not declared private, in other classes as well. Because the variable is shared, a change made to it inside a subroutine can have effects that extend beyond that subroutine. The next program is an original example. The counter lives outside increment, so each call changes the same stored value, and main sees the result after both calls return.

The source is careful not to forbid the practice. Global variables are not always bad inside subroutines. If the global variable is treated as part of the subroutine's interface, the communication is acceptable. The source recommends asking, before you use a global variable in a subroutine, whether it is really necessary. The comparison below sets out what a caller has to know in each case.

The comparison is an interpretation of the source's point about interfaces, not a rule the source states in this exact form. The source's core claim is that a shared variable becomes part of the subroutine's interface, and that a black box should have an interface that is straightforward and easy to understand.

A subroutine does not run just because it exists in a program. It runs when the program reaches a point where it calls it. Imagine a program that needs the same job done in three places. You could copy the same lines three times, or write them once and call them wherever they are needed. The next program is an original example that calls one subroutine twice from main, once before a heading and once after. Each call transfers control into the subroutine, runs its body, and returns control to the exact place where the call was made.

The source describes ThreeN2.java as an improved version of the 3N+1 program, introduced in Section 4.4. It is described as a program that uses subroutines and prints its output in neat columns. The source gives two reasons for the 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.