Functions and Routines in Java

Most useful programs are assembled from pieces that someone else wrote. A programmer who needs to sort records, draw a window, or solve a complicated equation rarely builds that machinery from nothing. Instead, they use a collection of ready-made routines and call them when needed. That raises an immediate practical question: if you did not write the routines, and you have no wish to study how they work internally, what do you actually need to know in order to use them correctly?

This article develops that answer. The short version is that the routines you call come with a published outside, and that outside is what you must understand. The inside, meaning the instructions that do the actual work, can stay hidden without getting in your way.

Start with a physical picture. Imagine you are handed a sealed box of tools. You can see a labeled panel on its front with a few buttons and a slot for input. You press a button, feed in material through the slot, and something comes out the other side. You never see the gears or circuits that do the work. Nothing about your task requires you to see them. The panel is the only part you have to understand.

Now trace the same situation through a software toolbox. Your program holds a reference to a collection of routines. Before you call any of them, the only facts available to you are the names of the routines, the inputs each one takes, and the task each one carries out. Everything the routine does between receiving those inputs and returning a result is invisible at the point where you call it. Keep that boundary in mind, because the rest of this article depends on it.

Read the diagram from top to bottom. The programmer's code never touches the implementation directly. It reaches the workings only through the specification, and the workings sit behind that specification. The specification is the surface you have to understand. The implementation is the part that can change without changing how you call the routine.

The API is the abstraction through which a programmer reaches a toolbox's functionality, which makes it the point of contact that users must understand. Each entry in an API tells you three things. It tells you the routine's name, which is how you refer to it. It tells you the parameters, which are the information you must hand over. It tells you the task, which is what the routine accomplishes. The specification does not show how the task is carried out.

Abstraction is the practice of exposing only the information the outside world needs while hiding implementation details behind the interface. The word describes a deliberate choice about what crosses the boundary. A good interface gives the user enough to call the routine correctly and to predict its result, and nothing more.

Keeping the question of how something is done separate from the question of what it does is the central idea behind APIs and abstraction. A user asks what a routine does and what it needs. The implementer answers how it does the work. Because those questions are kept apart, the user does not have to study the machinery to use it, and the implementer is free to work on the machinery without changing the description the user relies on.

Consider what happens when a caller invokes a routine. The caller supplies the inputs described by the specification. Those inputs travel into the routine as parameters. Inside the routine, the task is carried out, which is the part the caller cannot see. Finally, a value comes back to the caller as the result. The specification tells the caller where to put the inputs and what result to expect, and that is enough to use the routine.

Notice which steps the specification covers. The parameters and the returned result are both on the exposed side of the boundary, because the caller must know them. The routine task sits in the middle, hidden. This is why the description of a routine focuses on inputs and outcomes rather than on the steps taken between them.

The idea is not specific to software toolboxes. The source describes a toolbox of graphical routines, a hardware card, and a library of mathematical methods. Each presents a published interface and keeps its internals out of view. The principle stays the same across all of them, so a user can work without understanding the underlying computations.

In the hardware column, the panel and the input slot are what you use, while the gears and circuits do the work out of sight. In the library column, the name, inputs, and result are the published side, while the computation steps stay internal. The two columns have the same shape. Only the kind of system differs.