Read an Excerpt
Chapter 7: The Programming Process
Maintenance Good programmers put their programs through a long and rigorous testing process before releasing it to the outside world. Then the first user tries the program and almost immediately finds a bug. This starts the maintenance phase. Bugs are fixed, the program is tested (to make sure the fixes didn't break anything), and the program is released again.
Revisions
Although the program is officially finished, you are not finished with it. After it is in use for a few months, someone will come to us and ask, "Can you add a modulus operator?" So you revise the specifications, add the change to the program, update the test plan, test the program, and release it again.
As time passes, more people will come to you with additional requests for changes. Soon the program has trig functions, linear regressions, statistics, binary arithmetic, and financial calculations. The design is based on the idea of one-character operators. Soon you find yourself running out of characters to use. At this point the program is doing work far beyond what it was initially designed to do. Sooner or later you reach the point where the program needs to be scrapped and a new one written from scratch. At this point you write a new Preliminary Specification and start the process over again.
Electronic Archaeology
Unfortunately, most programmers don't start a project at the design step. Instead they are immediately thrust into the maintenance or revision stage. This means the programmer is faced with the worst possible job: understanding and modifying someone else's code.
Contrary to popular belief, most C++ programs are not written by disorganized orangutans using Zen programming techniques and poorly commented in Esperanto. They just look that way. Electronic archeology is the art of digging through old code to discover amazing things (like how and why the code works).
Your computer can aid greatly in your search to discover the true meaning of someone else's code. Many tools are available for examining and formatting code. (Be careful with your selection of tools, however. Many C tools have yet to be upgraded for C++. See earlier sections on revisions.) Some of these tools include:
Cross-references. These programs have names like xref, cxref, and cross. System V UNIX has the utility cscope. They print out a list of variables and where the variables are used.
Program indenters. Programs such as cb and indent indent a program "correctly" (correct indentation is something defined by the tool maker).
Pretty printers. A pretty printer such as vgrind or cprint typesets source code for printing on a laser printer.
Call graphs. On System V UNIX the program cflow analyzes the structure of the program. On other systems there is a public domain utility, calls, that produces call graphs, showing who calls whom and who is called by whom.
Class browsers. A class browser allows you to display the class hierarchy so you can tell what components went into building the class as well as its structure. You'll learn what a class is in Chapter 13, Simple Classes.
Which tools should you use? Whichever ones work for you. Different programmers work in different ways. Some techniques for examining code are listed below. Choose the ones that work for you and use them.
Mark Up the Program
Take a printout of the program and make notes all over it. Use red or blue ink so you can tell the difference between the printout and the notes. Use a highlighter to emphasize important sections. These notes are useful; put them in the program as comments, and then make a new printout and start the process over again.
Use the Debugger The debugger is a great tool for understanding how something works. Most debuggers allow you to step through the program one line at a time, examining variables and discovering how things really work. Once you find out what the code does, make notes and put them in as comments.
Use the Text Editor as a Browser
One of the best tools for going through someone else's code is your text editor. Suppose you want to find out what the variable sc is used for. Use the search command to find the first place sc is used. Search again and find the second. Continue searching until you know what the variable does.
Suppose you find out that sc is used as a sequence counter. Since you're already in the editor, you can easily do a global search-and-replace to change the variable sc to sequence_counter. (Disaster warning: Make sure sequence_counter is not already defined as a variable before you make the change. Also make sure you do a word replacement or you'll find you replaced sc in places you didn't intend.) Comment the declaration and you're on your way to creating an understandable program.
Add Comments
Don't be afraid to put any information you have, no matter how little, into the comments. Some of the comments I've used include:
int state; // Controls some sort of state machine
int rmxy; // Something to do with color correction?
Finally, there is a catch-all comment:
int idn; // ???
which means, "I have no idea what this variable does." Even though the purpose is unknown, it is now marked as something that needs more work.
As you go through someone else's code adding comments and improving style, the structure will become clearer to you. By inserting notes (comments), you make the code better and easier to understand for future programmers.
Suppose you are confronted with the following program written by someone from the "The Terser the Better" school of programming. Your assignment is to figure out what this program does....
