There are two audiences that every programmer must consider when developing an application. First, the code must be "programmer-friendly." In other words, it must be easy for programmers, other than the original coder, to read and understand. Second, the program must be "user-friendly" by showing consideration for the people who will operate it on a regular basis. Creating programmer-friendly code is covered in the latter half of this handbook. This section deals with how to write applications with the user in mind.

Being computer users, programmers deal with a host of tools and utilities everyday. Some applications are a joy to use, others a nightmare. This fact raises two key questions: "What does user-friendly mean?" and "How can I make my program more friendly?" The simple answer to the first question is that a user-friendly program is one that the user considers a friend instead of an enemy. Answering the second question is more challenging. For years, computer scientists have tried to come up with a set of laws to define what makes a program amicable. On the following page, I have provided a list of tips that you can apply to your user interfaces, to improve the overall user-friendliness of your programs.

When working on user interfaces, every programmer should keep in mind three key areas: data validation, input, and output.^{[Robertson 93]} Data validation refers to the process of checking that input is valid. One of the main reasons that programs produce unexpected results is due to invalid or unforeseen input; for example, receiving an out of bounds value. This is commonly referred to as the "garbage in, garbage out" principle. As a safety precaution, data should be validated as close to the point of entry as possible. You may even want to consider data entry and validation as the same step.

As far as program input and output is concerned, do not make assumptions about what the user wants, needs, or likes. If you are unclear as to how the user expects the interface to work, ask! This should be standard practice, as it will save time in the long run if the client has unique requirements that you may not be aware of; for example, perhaps the user expects all of the output to be sent to a remote printer, and all input to come from a special data file.

Above all, keep in mind that the only experts on the user interface are the people who use it. If you put yourself in the shoes of the user, you can better manage the development of a user-friendly program. Following this fundamental idea, the next page lists some specific advice for the construction of programs which show consideration for the user.

· Follow the "Principle of Least Astonishment." In other words, your program should always act in a way that least surprises the user. Be sure that you understand exactly what the client wants from the system. Remember that the user has a job to do, and they want the computer to do that job, their way, with minimal effort.

· Make error/warning messages clear and helpful. It goes without saying that a user-friendly program must include messages to indicate errors and warnings, either caused by the program, or the user. As a convention, you should begin each error message with "Error:", and each warning message with "Warning:". Messages should not be cryptic or require the user to know any computer terminology. Use plain English. Below is a poor example of an ambiguous error message many PC users have encountered during boot-up:

· Provide some sort of help system. In the past, programs where designed to conserve resources. Today, they are designed to maximize usability. The amount of help to provide depends on the application and the skill level of the user. The help given may be as elaborate as a context sensitive help system, or as trivial as a simple message; but it should always be provided.

· Friendly programs have built-in safety nets. Occasionally, a user may try to do something that will result in permanent damage or loss of data. A user-friendly program should provide a safety net preventing truly stupid actions, or at least warn users if they are about to do something they may regret. In short, do not let users shoot themselves in the foot unless they really want to.

· Furnish accelerators for experienced users. "Power users" always appreciate the ability to use a program with fewer keystrokes. For example, to print in WordPerfect 5.1, Shift-F7 is preferred by the veteran user over Alt-=, F, P.

· Apply the principle of modularization to the user interface. Isolate as much of the interface code as possible from the mechanics of the rest of the program and the machine it runs on. Modular code, and User Interface Management Systems (UIMS) can help you avoid rebuilding your program's user interface from scratch, if your system is ported to a new platform.

Recall that a data type is characterized by the values that its objects can assume, and by the operations that can be carried out on them. In typed languages, such as C and C++, the allowed values for a specific type are determined when the type declaration is made. An important property of any general purpose programming language is the ability to allow the creation of user defined types. User defined types that encapsulate both data and functions together are referred to as abstract data types, or ADTs.^{[McConnell 93]}

The concept of creating brand new types is exciting because it makes it possible to represent real-world entities within the code itself. More specifically, ATDs allow programmers to solve problems in the vocabulary of the problem domain rather than in computer science lingo. For example, instead of implementing a conventional queue data structure, with get_front() and add_back() functions to represent a line of people at a bank machine, we could define a "bank_line_up" abstract data type. Within this type we could further define routines to serve_next_patron() and add_new_patron() etc.. The ability to manipulate real-world objects in the problem domain not only helps to deal with complexity, but it makes for a more readable and maintainable program!

Virtually all modern languages are capable of supporting the implementation of some form of abstract data type although some languages are better at it than others. The ability of object oriented languages to support real-world entities through classes and objects have made languages like C++ very popular. For those unfamiliar with the Object Oriented Programming (OOP) paradigm, a class is a type of definition that merges data and functions together under a single framework, and an object is an instance of a class.

A circular number is an integer which may assume only those values within a given range. If you try to increment past its range it will return to its minimum limit and, similarly, if you decrement past the beginning of its range, the number will shift back to its maximum limit. So, as far as data is concerned, each circular number has a value, a minimum limit, and a maximum limit. The class definition also requires numerous functions to facilitate the manipulation of the circular number. Consider the C++ circular number abstract data type below:

Notice that all of the data values are declared within the private section of the definition. This means that any functions outside of the class (ADT) can not directly access them. In order to enable outside code to look at or modify the module data, seven simple access functions have been provided in the public section of the data type. Finally, notice that a supporting function, add(), has also been made private. In this implementation, a design decision was made to hide the add() function from general use outside of the ADT.

Please realize that even if your language does not support classes and objects directly, you should still be able to implement abstract data types very effectively. I have simply chosen to use C++ due to its clarity and the fact that classes very closely parallel abstract data types and modules.

Since classes, abstract data types, and modules are all defined as entities which include both data and the operations to manipulate the data, all three share these benefits:^{[McConnell 93]}

· They hide implementation details. With modular code it is possible to change the internal design of module data or functions, without affecting the rest of the program that uses it. A good analogy would be that you can change the interior of your house as much as you want. As long as the exterior is unchanged, your friends can still easily find it. For example, if the add() function was optimized with assembler code, as long as it performed the same task, no other code would need to be changed. Also, any code within the data type that called the function would benefit from the optimization.

· They remove the need to pass data throughout the program. If the class, abstract data type, or module internally hides data that it manipulates, it promotes data integrity because you have centralized control over the data. In other words, data is "fire-walled" from inadvertently being damaged through unexpected direct access.

· They allow you to work in the vocabulary of the problem domain. This helps to deal with complexity and make programs more self-documenting.

The purpose of this section is not to demonstrate how to implement abstract data types and modules in every language, but rather to make you aware of the main ideas behind them. Often the hardest part of implementing modular code is deciding which features should be known outside of the class, ADT, or module, and which should not. Below are common details to hide.

· Any variable or routine that does not need to be directly accessed externally. By hiding as much as possible, the benefits of modularity may be maximized.

· Areas likely to change. The goal here is to isolate code so that the effect of any modification will be limited to one module. Some good things to isolate in modules are user interface details, system calls, hardware dependencies, and low level screen and printer use. This way, if the system is ported, perhaps only that class, ADT, or module will need to be rewritten.

· Complex data or logic. By hiding complicated code within a class, ADT, or module, complexity is reduced, and code is more readable overall. Also, if you discover a better way to implement an intricate feature, you can simply change the access functions; the outside code will be unaffected. Data management routines may be packaged to hide unnecessary details for various data or file structures thus allowing the user to manipulate data in an abstract way.

You should make an effort to assemble a library of general classes, ADTs, or modules, that can be used in several contexts within different projects. Your routines and modules should be general enough to be applicable to a wide variety of programs and make it possible to replace or change the internal implementation of a routine, or group of associated routines, without seriously affecting the rest of the program.

Strong cohesion and loose coupling are two metrics used to gauge the level of modularity for a routine or set of related routines (class, ADT, or module). To begin, a cohesive routine is one in which the entire routine is dedicated to a single purpose. For example, the trigonometric function Tan() is perfectly cohesive because it clearly performs only one job. The function TanAndCos() would be classified as less cohesive because it is intended to perform more than one task. Design your routines for strong cohesion. The payoff will be code which is less complex, easier to debug, and modify.

Within classes, ADTs, and modules, the criterion for strong cohesion is very similar to that with individual routines. They should provide a group of services that clearly belong together. For example, the circular number class earlier consisted only of data and functions related to a single purpose. The class was strongly cohesive. Appreciate that just because the routines in a module are related does not guarantee that each individual routine is cohesive. Always aim for strong cohesion with both routines, and sets of routines.

The second measure of modular code quality is coupling. Coupling refers to how simply routines and modules are physically connected to each other. Loose coupling is the complement of strong cohesion. Good coupling should be loose enough that each routine can easily be called by others. In order to achieve this goal two main criteria must be met.

First, the number of parameters to interface with a routine should be minimized.^{[McConnell 93]} It also helps if you use a parallel ordering of parameters for routines that perform similar jobs. For example, a set of mathematical functions that only have two or three parameters each, and where the ordering of parameters is consistent, would be easier to remember how to use than a set of routines with a dozen parameters each, and where the ordering of the parameters is dissimilar in each case.

Second, the connections between all routines should be as visible as possible.^{[McConnell 93]} In other words, you should avoid using global data to pass information to and from routines as this hampers the "plug and play" benefit of modularity. For example, a routine that depends on a global variable is not as easy to reuse in a different project, than a routine which does not rely on an external variable to do its job.

In any language, variables with large scope should be avoided because their use does not encourage loose coupling. Their use is also risky because inadvertent modification of data with a broad scope is hard to detect. As well, they hinder code reuse because routines that access data outside of their scope are harder to "pull out and plug into" another program. To avoid using variables of large scope, start by minimizing the scope of new variables and increase their scope only as needed. The reason for this is that if you start a variable with a large scope its scope may never become minimized, and vice versa. Lastly, realize that some variables only need to be accessed by a set of routines; these are module variables. Rarely, some variables need to be accessed throughout an entire program; these are the global ones.

The overall idea behind modular code construction is that once a routine or set of routines is written and tested, you should be able to take them for granted. Remember, routines are just an intellectual tool for dealing with complexity. If they are not simplifying your code, they are not doing their job.

Effective design is not easy to learn or teach. This is unfortunate because it is the key ingredient to a quality program. A good design should promote strong modular cohesion with loose coupling. As well, it should minimize complexity and make the system easier to maintain and extend in the future. Following a top-down or bottom-up approach, or perhaps a mixture of the two, routines should be logically planned to perform a well-defined task in the problem domain. Although there are many different methods for designing routines, here is a basic five step process that you might find helpful: ^{[McConnell 93]}

1] Check to ensure that the routine is actually needed based on the functional requirements of the program. The routine should have a well-defined purpose, and fit cleanly into the existing architecture. See if it is possible to reuse a previously constructed, generalized, routine. Code reuse is a good way to improve your productivity and the overall quality of your code.

2] If a new routine is needed, consider exactly how it will handle errors and the type of errors which are most likely to occur. It is important to think about this now, as it affects the next step. Figure out what the routine will hide, its inputs and outputs (including any global variables affected), and performance requirements. Based on the job the routine will do, give it a meaningful name. Good names help to improve readability; naming is fully covered in Part 2.

3] Keeping in mind the most probable sources of error identified in step #2, prepare a detailed test plan or suite. Maintaining a list of what to test, how to test it, and the expected result(s) is a step toward a more reliable program.

4] Write the routine in a Program Design Language (PDL) or pseudo-code (more information on PDLs can be found in McConnell's book Code Complete). The purpose of the previous steps was to establish a mental familiarisation with the overall problem the routine must solve. Start with a general idea and work toward something more specific. Keep refining it until you feel confident that your design is "bullet proof" and easy to translate into the actual programming language. Try alternative designs with a PDL before you start coding.

5] Write the heading comment for the routine to help focus your thoughts, and then translate from the PDL to the actual implementation language. Next, move on to the testing, debugging, and optimization stages of construction.

Testing is a difficult art. It requires a unique set of skills and a different mental attitude than analysis and coding. Interestingly, programmers often have difficulty testing their own code. The reason is because they focus on making a program fulfil certain criteria and as a result have difficulty imagining some of the more unorthodox ways others may use their code or application.

Section 2.2 extolled the virtues of designing routines and abstract data types such that other programmers can use them without having to understand their internal workings; that is, to treat them like "black boxes," where they know what goes in and what to expect out, but nothing about the actual mechanics of the code. Testing done by the original developer is known as "glass box" testing, because they fully understand not only what goes in and what to expect out of their routines, but also what goes on internally.^{[Robertson 93]} Glass box testing will be the focus of this section.

Glass box testing can be a time consuming process. How much time should be spent testing code? In reality, exhaustively testing code can take longer than it took to write it. Surprised? A major misconception about testing is that testing time cuts into programming time. This is simply untrue, because testing time is programming time. More clearly, you should constantly test code as you write it, as well as fully testing the end product.

Consider testing an input routine which accepts a string of 20 digits. To demonstrate that the routine works for all possible inputs would involve 10²⁰ test cases. Clearly, in a large scale application, it would be virtually impossible to exhaustively test potentially thousands of routines. Therefore, practical testing must involve a systematic approach, or test plan, to intelligently focus on cases that are most likely to cause problems.

Developing an effective plan is not easy and requires the ability to anticipate planned design elements and exigencies of change over time. Testing can be done manually or in an automated fashion. Manual testing works well for checking individual routines or modest sized applications. However, in general, it usually involves less coverage than automated testing. Automated testing requires a master program or test scripts to monitor multiple iterations of detailed test cases. The main benefit of this type of testing is that it always follows the same path; therefore, detected errors can be recorded and reproduced. Testing without a plan is like flying without an airplane -- it is over quickly and the results are less than satisfactory. Regardless of the scale of your project or the method of testing used, the following advice should help you detect errors with minimal effort.

Beginning programmers often have difficulty distinguishing between testing and debugging. Recall that testing is the process of executing the code for the purpose of detecting errors, whereas debugging is the process of diagnosing and correcting their root causes. One of the major difficulties of debugging is that the causes of errors vary depending on the language, hardware, and operating environment used. Most commonly, bugs are caused by: off-by-one errors, array overruns, dynamic memory allocation, invalid pointer assignments, incorrect function parameters, signed/unsigned confusions, type conversions, and incorrect termination of loops and recursion.^{[Robertson 93]}

Ironically, good programmers often do not make good debuggers. As with testing, debugging can be an exhausting art. The most important thing when debugging is not to make assumptions about your code. Far too often programmers immediately blame the computer or compiler for problems with their code. Programs are logical; they do not "do something different" every time they are run. Remember that your program did not make itself -- you did! A respectable programmer takes full responsibility for his or her code.

Aside from the proper mind set, debugging demands the skills of both a physician and a detective. Like a doctor, a programmer must determine which symptoms are relevant to the error (illness) and which are not. As well, through experience, you must learn what kind of bug (germ) tends to generate the kind of problem (ailment) in question. Once the source of the problem is isolated you must decide how to remedy the situation. Is it simply a typo, or does the design have to be rethought?

As a detective, a programmer must be able to examine the code (facts) and find clues regarding the nature of the problem. Again, it is most helpful to assume that the source of the error is in fact within the code. Identifying the source of the problem can take a long time. A good debugger must have the persistence to locate bugs. This is especially true when you are learning new things along the way and have to start over because of it. Remember, these skills come from experience. You must practice debugging and develop a system that works best for you.

When debugging it is always a good idea to start tracking the bug at the highest level most likely to contain the error in your code. If you are unable to isolate the cause of the problem at that level, move down one level lower in the code and repeat the process until the bug is found. The reasoning behind this method is that debugging complexity and effort increase as you go into the deeper layers of source code.

In the past, many programmers tended to focus on squeezing as much functionality out of each line of code as possible. After all, it was thought, is this not how you maximize code performance? Well, the answer to that question depends on the current definition of "performance." Today, performance is only loosely related to code speed and size. Other factors are now being considered part of overall performance; considerations such as providing an easy to use interface, reliability, readability, and assisting long-term maintainability are all key metrics of performance.^{[Abrash 94]} Clearly, a few outdated misconceptions must be dealt with:

Fallacy: You should optimize as you go.

Response: It is practically impossible to identify performance bottlenecks until you have a completely working program. Prematurely focusing on optimization is a waste of time and in the end hurts code quality by distracting concentration from the main objective.

Fallacy: It is always worthwhile to optimize code by hand.

Response: Modern compilers are often better at optimizing code than many people think. In fact, hand optimization may defeat compiler optimizations that have been designed to work with more straightforward code. Therefore, unless you have a poor design or algorithm to begin with, compilers today should do a good job of producing efficient code -- don't make extra work for yourself by fussing over it. Remember, it takes time to hand tune initially, and it is harder to read later on.

Fallacy: Certain operations are faster or smaller than others.

Response: This is partially true. Generally, I/O, system calls, and floating point calculations take time. However, these facts change among operating systems, hardware configurations, languages, compilers, and even versions of a compiler. Therefore, to maximize portability hand tuning is not always the best idea.

As general rule of thumb, you should begin with a good algorithm and high-quality design, make the code correct and easy to maintain, and then check performance. If it lumbers, then it may be worthwhile to fine tune. Do not optimize unless you are sure that it is absolutely essential.

Code maintenance begins when the first bug occurs and you must go back and repair it. In the software engineering industry, a great percentage of resources go to program upkeep, or the act of replacing unmaintainable code. One of the reasons for this problem is that human nature tends to be more interested in the here and now than later.

Inconsiderate programmers often feel that it is easier to make a program that simply works today, than to design it to last for years. Thoughtful programmers always remember that the reward for well-written code may not be realized until much later in the process -- when it is time for a major upgrade or if a significant flaw is uncovered. In the real world no one codes in a vacuum, so be considerate for the next programmer down the road, and expect others to be considerate toward you.

Too many helpful construction tips have been presented in this chapter to reiterate here. A few of the key ideas for constructing quality code are:

· Quality construction involves: design, testing, debugging, and optimization.

· The ecumenical goal of the four phases is long-term program maintainability.

· Understanding the four phases is the key to becoming a good programmer.

· Programs must not only be programmer-friendly, but user-friendly as well.

· When developing a user interface always put yourself in the user's position.

· Modularity promotes maintainable, independent, lean, and stratified designs.

· The notion of strong cohesion and loose coupling is essential to modularity.

· Always minimize the scope of data objects, and avoid global variables.

· ADTs are easy to implement if you understand modular code construction.

· A modular (maintainable) design must involve a logical development process.

· Effective testing (manual or automated) must be systematically conducted.

· Debugging requires the right mind set, and the skills of a physician/detective. · It is best to debug from the highest (least complex) level of code to lowest.

· Today, code performance involves factors other than simply speed and size.

· Optimize working code only if a good algorithm and design are not enough.

· The long-term rewards for quality code far outweigh any short-term costs.