A procedure in C++ is like a paragraph in a book. It is used to express a single, coherent thought. Just as a paragraph deals with a single subject, a procedure should perform a single operation. Ideally you should be able to express what a procedure does in a single simple sentence. For example:

A badly designed procedure tries to do multiple jobs. For example:

It’s the body of the procedure that does the actual work. A procedure should do its job simply and coherently. In general, programmers design and work on an entire procedure at a time, so the procedure should be small enough that the whole procedure can fit in a programmer’s brain at one time. In practice this means that a procedure should be only one or two pages long, three at the most.

Design Guideline: Procedures should be no more than two or three pages long.

Global variables

All the variables used by a procedure are either local to the procedure or parameters except for global variables. (The word “except” is an extremely nasty word. Frequently it indicates a complication or extra rule. Things were probably simple before the “except” came into the picture.)

The use of a single global variable inside a procedure makes the whole procedure much more complex. For example, suppose you want to know what a procedure does for a given call. If that procedure uses no global variables, all you have to do is look at the parameters to that procedure to figure out what is going to happen.

You can determine what the parameters are by looking at a single line in the caller. All the other variables are local to the procedure. That’s only three pages long, so you probably can figure out what happens to them.

But now let’s throw in a global variable. That means that the input to the procedure is not only the parameters, but the global variable. So who sets it? Because the variable is global, it can be set from just about anywhere in your program. Thus, to determine the input to a procedure, you must analyze not only the caller, but also all the code in the entire program. I’ve seen people do string searches through tens of thousands of files trying to find out who’s setting a global variable.

Figure 26-1 shows the information flow into and out of a procedure and how this is affected by global variables

Figure 26-1. Procedure inputs and outputs

One way people try to get around this problem is to require that all programmers list the global variables used by their procedures in the heading comments to the function. There are a couple of problems with this. First of all, 99.9% of the programmers don’t do it and the other 0.1% don’t keep the list up to date, so it’s totally useless. In addition, knowing that a procedure uses a global variable doesn’t solve the problems caused by not knowing when and how it is used by the outside code.

Design Guideline: Use global variables as little as possible.

A collection of closely related procedures in a single file is called a module. Modules are put together to form a program. The proper organization of modules is a key aspect of program design.

First, your module organization should be as simple as possible. Figure 26-1A shows a program with seven modules. With no organization, there are 42 connections between the modules.

Figure 26-2. Module interactions

A programmer who is debugging a module must make sure that the other six modules he deals with work. Any problems in them are her problem. Testing such a system is a problem as well. To test one module, you need to bring in the other six. Unit testing of a single module is not possible.

Now consider the organization in Figure 26-1B. This system uses a hierarchical module organization. Consider the benefits of this organization. The modules at the bottom level call no one, so they can be tested in isolation. After these modules pass their unit tests, they can be used by the other modules.

People working on the middle-level modules have to contend with only two sub-modules to make sure their module works. They have some assurance their modules work—after all, they did pass the unit test—so the middle-level programmers can concentrate on dealing with their own modules.

The same thing holds true for the person dealing with the top-level modules.

By organizing things into a hierarchical structure, we’ve added order to the program and limited problems.

Design Guideline: Arrange modules into a organized structure whenever possible.

store_char -- Stores a character in the buffer
n_char -- Returns the number of characters in the buffer
flush_buffer -- Writes the buffer out to disk

store_char(io_ptr, ch);
if (n_char(io_ptr) >= MAX_BUFFER)[]
    flush_buffer(io_ptr);

write_char(io_ptr, ch) -- Sends a character to a file.

Let’s see how a set of modules can be organized in real life. In this case we are dealing with a computer-controlled cutter designed to cut out tennis shoes. The major components of this device are:

The basic design results in five major modules:

A diagram of the major pieces can be seen in Figure 26-3.

Figure 26-3. Cutting system, module design

This organization, although not quite hierarchical, is quite simple. Each module has a well-defined job to do. The modules provide a small, simple interface to the other modules.

The other thing about the modules is that they are designed to be independently tested. For example, when the project started, the machine didn’t exist. What we had was a computer, a pile of parts, and a lot of stuff on back order. Since the workflow manager didn’t require any hardware, it was developed first. The other modules were faked with test routines. The fake routines used the same interface (header files) as the real ones. They just didn’t do any real work.

It is interesting to note that the unit tests were used to test not only the software but the hardware. The unit test for the positioner module consisted of a front-end that sent various goto commands to the system. The first few tests were a little hairy because the limit switches had not been installed on the hardware, and there was nothing to prevent us from running the cutting head past the end and damaging the carriage. (Actually, the limits were rigorously enforced by a nervous mechanical engineer who held his hand inches above the emergency power off for the entire test. He wasn’t about to let our software damage his hard work.)

This module structure let us create something that was not only simple, but testable. The result is increased reliability and decreased integration and maintenance costs.

So far we’ve learned a lot about how to design and organize our code. But programming deals with data as well as code. In the next few sections, we’ll see how to include data in our design through the use of object-oriented design techniques.

Ideally, when you publish an interface you want to publish only the public data. In C++, to publish the interface for a class, you include the class definition in a header file. There is a problem, however; the class definition includes both public and private data.

This can cause problems.

Let’s go back to our machine tool example. We had a hardware support module; it’s a published interface (header file). For testing, we replaced it with a hardware simulation module that used the same published interface (the exact same header file).

When the interface is a class, you can’t do that. That’s because your hardware support class will probably have different private members than the simulation support class. Thus you need to keep two header files around, one for the hardware module and one for the simulation.

The public information in these header files must be duplicated, and thus you have all the problems associated with trying to keep two different files up to date and synchronized.

Unfortunately, C++ is not perfect, and the fact that private information must be published is one of its big problems.

The linked list problem is actually a C problem, but the various solutions and its ultimate solution in C++ provide a good understanding of the various techniques that can be used to solve a problem.

The code I’m working on now has several linked lists:

There is an insert and delete function for each type of list:

insert_msg / remove_msg
insert_run  / remove_run
insert_kbd / remove_kbd
insert_idle / remove_idle
insert_connect / remove_connect
... and so on

This is a needless duplication of code. There has to be a better way. In C, one solution is to play games with the data. The trick is to define a common linked-list structure:

/* C Code */
struct list_head {
    struct list_head *next, *prev;
};

This structure is put at the start of each data structure that may be used in a linked list:

/* C Code */
struct pending_message_node {
     struct list_head list;     /* List info.  Must be first */
     struct message the_message;/* The stored message */
};

Now we can take advantage of the fact that each mode in our pending message list begins with a list_head, use casting to turn our pending_message_node into a generic node, and use the generic linked list procedures on it:

/* C "solution" to a difficult code reuse problem */
struct pending_message_node *pending_messages = NULL;
struct pending_message_node *a_new_message;

/* Fill in node */
add_node_to_list(
    (struct list_head *)pending_messages,
    (struct list_head *)a_new_message);
/* Note the C style casts.  This is C code */

This technique depends on the fact that the compiler lays out the memory for a structure with the first field (in this case list) first. This sort of layout is not required by the standard, but almost all compilers do it. (And those that don’t cause people who depend on this feature a lot of headaches. They’ll be forced to rewrite their code so it doesn’t depend on compiler-dependent features.)

The C solution to this problem is pretty good given the limitation of the C language. But the C++ language gives us many more techniques for solving this problem.

The use of C casts is just the poor man’s way of doing base and derived classes. The C++ equivalent is:

/* Not a good solution.  See below */
class list {
    private:
        list *next;
        list *prev;
    public:
        // Rest of the stuff
};

class pending_message_node: public list {
    // .... message data
};

But there is a problem with this organization. The list and the message have nothing in common. A list is not a refinement of a message, and a message is not a refinement of a list.

Code that wants to process a message and doesn’t want to deal with a list item can’t deal with a pending_message_node. We could write it as:

/* Not a good solution still */
class list {
    // ...
};
class pending_message {
    // ...
}
class pending_message_node: public list, public pending_message {
   // Nothing needed here
};

This “structure” merely rearranges a badly designed data structure into one that’s even more silly.

Ideally we want to organize our information like this:

class pending_message {
    // ...
};

class pending_message_list {
    // List stuff
    public:
        class pending_message message;
};

But now we’re back to the problem that started this discussion. We’re going to have to create a list for every type of object:

class msg_list ....
class keypress_list ...
class event_list ...
class free_block_list ...

This means that to properly design our data, we’re going to have a lot of almost identical classes. This would be a lot of duplication of effort, except for one thing: templates. The result is that we can write all these classes using one template:

template class list<typename data> {
    // List stuff
    public:
        data node;
};

One last note: it’s a little easier that this. We don’t have to write the list class ourselves. It’s already part of the Standard Template Library (STL):

#include <list>

class msg { /* .... */ };
std::list<msg> message_list;

class keypress { /* ..... */};
std::list<keypress> keypress_list;

Thus we’ve taken the long way round to discover that all you need to solve the “list problem” is to use the STL. But it’s interesting how the problem can be solved using a language with limited features (C), as well as seeing a number of designs to avoid.

Let’s suppose you are writing a text editor. There are three main modules to this program:

One of the keyboard module’s jobs is to read the keyboard input and call the appropriate command function. The mapping of keys to commands is accomplished through the use of a configuration file (also under control of the keyboard module).

So to do its job, the keyboard module needs to know the names of all the commands and what function to call to execute them.

One way to organize this information is to create a table containing this information and give it to the keyboard processor:

struct cmd_info {
     const char *command;
     void (*function)(  );
}[] cmd_table = {
     {"delete", do_delete},
     {"search", do_search},
     {"exit",   do_exit},
    ....

But this means that the module containing the table must know every command in the system. This way of doing things causes two major problems. First, we have discarded our module hierarchy and invalidated some of the information hiding we have so carefully built up. Now, one module, the command table module, needs to know everything. Second, we have to maintain the thing. Any time any one of the command modules changes, the file containing the command table must change as well.

Figure 26-5 shows our module layout.

Figure 26-5. Editor module design

A better solution is to build this table at run time. During initialization time, the top command module is told to register all the user-level commands. For example, it may register the “exit” command:

keyboard_module::register_command("exit", &do_exit);

The top-level command module knows about its submodules and tells them to register their commands. They in turn call the subsubmodules, and so on.

The result is that the command table is built up at run time. Thus, we let the computer keep track of all the commands instead of doing it manually. This is more reliable and easier to do.

Figure 26-6 shows these module interactions.

Figure 26-6. New Editor module design

Thus callbacks let us organize things so that the program configures itself automatically.

Let’s suppose we wish to create a simple database. In it we will store a person’s name and phone number. A class to handle this might look like the following:

class phone_book {
    public:
         void store(const std::string& name, const std::string& number);
         std::string& lookup(const std::string& name);
         void remove(const std::string& name);
         // .. additional member functions
    private:
         // Implementation dependent stuff
 };

This class definition is then stuck in a header file for all to use.

The problem is that we are forced by C++ to put implementation-dependent stuff in the header file. This means that the user knows implementation details that are none of her business. It also means that we cannot provide more than one implementation of our phone book class. (We could play some games with derived classes, but that just moves the problem down a level to the derived class.)

Let’s change our definition slightly and write our class as follows:

class phone_book_implementation;

class phone_book {
    public:
         void store(const std::string& name, const std::string& number);
         std::string& lookup(const std::string& name);
         void remove(const std::string& name);
         // .. additional member functions
    private:
         phone_book_implementation *the_implementation;
 };

Note that we did not define what the phone_book_implementation actually is. C++ is perfectly happy to create a pointer to it without knowing anything about it (other than that it is a class of some sort).

It is the job of the phone_book constructor to connect the implementation with the interface. In this example, we use a array-based phone book implementation:

phone_book::phone_book(  ) {
    the_implementation = new phone_book_array_implementatation;
}

But there is nothing to prevent us from using a hash-based implementation:

phone_book::phone_book(  ) {
    the_implementation = new phone_book_hash_implementatation;
}

Using this system, we’ve decoupled the implementation from the interface. This is a good thing (mostly). In this case the caller does not know which implementation was selected.

For example, we could use array-based implementations if we have, say, 1-100 names, a hash for 100-10,000, a small database such as MySQL for 10,000 to 10,000,000, and a commercial database for more than 10,000,000.

What’s more, it is possible to switch implementations at run time. For example:

phone_book::store(const std::string& name, const std::string& number) {
    number_of_entries++;
    if (need_to_switch_from_hash_to_mysql_database(  )) {
        phone_book_implementation *new_implementation =
            new phone_book_msql_impelemntation;
        copy_database(new_implementation, the_implementation);
        delete(the_implementation);
        the_impelementation = new_implementation;
    }
    // .. rest of the function
};

As you can see, this design has certain advantages. By decoupling the implementation from the interface, we’ve gained tremendous flexibility in choosing an implementation.

The design also has some drawbacks, the biggest of which is that it adds an extra layer between the phone_book user and the implementation. In most simple programs, this layer is not needed. Also, the use of derived classes in such a situation is no longer a simple matter of C++; instead, it requires some tricky coding. But this does serve to show what you can do with C++ to solve problems creatively.