Modular Programming with Functions

This article closes the 3N+1 discussion with a complete program. Earlier in the chapter, the function nextN() was defined on its own. Here you see the same function put to work inside a full program that asks the user for starting values, computes several sequences, and reports results. Instead of starting from the definition of nextN(), this article starts from the finished program and asks what each piece is doing, so that the function's role becomes visible in the context where it is actually used.

Begin by reading the program as a whole before following any single line. The opening comment describes the program's purpose in plain language: it computes and displays several 3N+1 sequences, the starting values come from the user, the terms are printed in columns with five on each line, and the number of terms in each sequence is reported after the sequence is shown. That description is a map. Each part of the program you read later should fit somewhere on it.

The program also gets a presentation upgrade. Its terms are printed in neat columns, five to a line. That change looks cosmetic, but it introduces a second idea that matters just as much: the program keeps a running count of how many terms it has printed on the current line, and uses that count to decide when to move to a new line.

A function that returns a value does its work and then hands a result back to whoever called it. The caller decides what to do with that result. It might store it in a variable, use it in a calculation, pass it to another function, or print it. Before tracing nextN() inside the larger program, it helps to test your expectations on a small function that has the same shape.

When the complete program needs the next term of a sequence, it calls nextN(). Control leaves the calling code, enters the function, and runs the function's body. When the function reaches its return, control goes back to the exact point where the call was made, and the returned value takes the place of the call in that expression.

The main program is not finished when nextN() is called. It is paused at the call, waiting for an answer. The returned value is what allows the paused work to continue. This is why a function call can appear inside an assignment or a print statement: the call is replaced by its result once control returns.

A returned value must be received somewhere. The caller might assign it to a variable, as in result = double_it(5), or it might let the call sit inside a larger expression, as in print(double_it(5) + 1). In both cases, you can find the receiving point by locating the call in the source and reading the statement it belongs to. The receiving statement is where the value is used, and it is the place to inspect when a value looks wrong.

The column layout depends on one simple idea, which the source states directly: keep track of how many terms have been printed on the current line, and when that number reaches 5, start a new line of output. The program does not need to know anything about the sequence's values to do this. It needs only a count that goes up each time a term is printed and gets reset when a line is finished.

To make the terms line up into neat columns, the program uses formatted output. Formatted output lets the program control how much space each printed value occupies, so that values in the same column start at the same position on each line. The source introduces this as the means of creating the neat columns, and the descriptive comment confirms the target of five terms per line.

Notice that the program never inspects the values 1 through 7 to decide where to break the line. The decision depends only on the count. Changing the printed values would not change where the line breaks, and a wrong count would move the breaks even if every value were correct.

When a complete program produces an unexpected result, the most useful question is where the result first went wrong. Because this program combines a called function with a running count, there are two natural places to look: the value that comes back from the function call, and the count that decides line breaks. Trace each one from the moment it is produced to the moment it is used.