Code Complete

cc2e.com/1234

Here are some of the specific tasks involved in construction:

• Verifying that the groundwork has been laid so that construction can proceed successfully
• Determining how your code will be tested
• Designing and writing classes and routines
• Creating and naming variables and named constants
• Selecting control structures and organizing blocks of statements
• Unit testing, integration testing, and debugging your own code
• Reviewing other team members' low-level designs and code and having them review yours
• Polishing code by carefully formatting and commenting it
• Integrating software components that were created separately
• Tuning code to make it faster and use fewer resources

1. Construction is a large part of software development
2. Construction is the central activity in software development
3. With a focus on construction, the individual programmer’s productivity can improve enormously
4. Construction’s product, the source code, is often the only accurate description of the software
5. Construction is the only activity that’s guaranteed to be done

Important developments often arise out of analogies. By comparing a topic you understand poorly to something similar you understand better, you can come up with insights that result in a better understanding of the less-familiar topic. This use of metaphor is called “modeling.”

A heuristic is a technique that helps you look for an answer. Its results are subject to chance because a heuristic tells you only how to look, not what to find. It doesn’t tell you how to get directly from point A to point B; it might not even know where point A and point B are. In effect, a heuristic is an algorithm in a clown suit. It’s less predictable, it’s more fun, and it comes without a 30-day money-back guarantee.

cc2e.com/0285

Among general books on metaphors, models, and paradigms, the touchstone book is by Thomas Kuhn.

Kuhn, Thomas S. The Structure of Scientific Revolutions, 3d ed. Chicago, IL: The University of Chicago Press, 1996. Kuhn's book on how scientific theories emerge,evolve, and succumb to other theories in a Darwinian cycle set the philosophy of science on its ear when it was first published in 1962. It's clear and short, and it's loaded with interesting examples of the rise and fall of metaphors, models, and paradigms in science.

Floyd, Robert W. "The Paradigms of Programming." 1978 Turing Award Lecture. Communications of the ACM, August 1979, pp. 455–60. This is a fascinating discussion of models in software development, and Floyd applies Kuhn's ideas to the topic.

• Metaphors are heuristics, not algorithms. As such, they tend to be a little sloppy.
• Metaphors help you understand the software-development process by relating it to other activities you already know about.
• Some metaphors are better than others.
• Treating software construction as similar to building construction suggests that careful preparation is needed and illuminates the difference between large and small projects.
• Thinking of software-development practices as tools in an intellectual toolbox suggests further that every programmer has many tools and that no single tool is right for every job. Choosing the right tool for each problem is one key to being an effective programmer.
• Metaphors are not mutually exclusive. Use the combination of metaphors that works best for you.

Choosing Between Iterative and Sequential Approaches

You might choose a more sequential (up-front) approach when

• The requirements are fairly stable.
• The design is straightforward and fairly well understood.
• The development team is familiar with the applications area.
• The project contains little risk.
• Long-term predictability is important.
• The cost of changing requirements, design, and code downstream is likely to be high.

You might choose a more iterative (as-you-go) approach when

• The requirements are not well understood or you expect them to be unstable for other reasons.
• The design is complex, challenging, or both.
• The development team is unfamiliar with the applications area.
• The project contains a lot of risk.
• Long-term predictability is not important.
• The cost of changing requirements, design, and code downstream is likely to be low.

The penalty for failing to define the problem is that you can waste a lot of time solving the wrong problem. This is a double-barreled penalty because you also don't solve the right problem.

Explicit requirements help to ensure that the user rather than the programmer drives the system's functionality. If the requirements are explicit, the user can review them and agree to them. If they're not, the programmer usually ends up making requirements decisions during programming. Explicit requirements keep you from guessing what the user wants.

Handling Requirements Changes During Construction

• Use the requirements checklist at the end of the section to assess the quality of your requirements If your requirements aren't good enough, stop work, back up, and make them right before you proceed. Sure, it feels like you're getting behind if you stop coding at this stage.
• Make sure everyone knows the cost of requirements changes
• Set up a change-control procedure
• Use development approaches that accommodate changes
• Dump the project If the requirements are especially bad or volatile and none of the suggestions above are workable, cancel the project.
• Keep your eye on the business case for the project Many requirements issues disappear before your eyes when you refer back to the business reason for doing the project.

Why have architecture as a prerequisite? Because the quality of the architecture determines the conceptual integrity of the system. That in turn determines the ultimate quality of the system. A wellthought- out architecture provides the structure needed to maintain a system's conceptual integrity from the top levels down to the bottom. It provides guidance to programmers—at a level of detail appropriate to the skills of the programmers and to the job at hand. It partitions the work so that multiple developers or multiple development teams can work independently.

The amount of time to spend on problem definition, requirements, and software architecture varies according to the needs of your project. Generally, a well-run project devotes about 10 to 20 percent of its effort and about 20 to 30 percent of its schedule to requirements, architecture, and up-front planning (McConnell 1998, Kruchten 2000).

cc2e.com/0344

Before construction begins, spell out the programming conventions you'll use. Coding-convention details are at such a level of precision that they're nearly impossible to retrofit into software after it's written. Details of such conventions are provided throughout the book.

Understanding the distinction between programming in a language and programming into one is critical to understanding this book. Most of the important programming principles depend not on specific languages but on the way you use them. If your language lacks constructs that you want to use or is prone to other kinds of problems, try to compensate for them. Invent your own coding conventions, standards, class libraries, and other augmentations.

• Every programming language has strengths and weaknesses. Be aware of the specific strengths and weaknesses of the language you're using.
• Establish programming conventions before you begin programming. It's nearly impossible to change code to match them later.
• More construction practices exist than you can use on any single project. Consciously choose the practices that are best suited to your project.
• Ask yourself whether the programming practices you're using are a response to the programming language you're using or controlled by it. Remember to program into the language, rather than programming in it.
• Your position on the technology wave determines what approaches will be effective—or even possible. Identify where you are on the technology wave, and adjust your plans and expectations accordingly.

The phrase "software design" means the conception, invention, or contrivance of a scheme for turning a specification for computer software into operational software. Design is the activity that links requirements to coding and debugging. A good top-level design provides a structure that can safely contain multiple lower-level designs. Good design is useful on small projects and indispensable on large projects.

• Software's Primary Technical Imperative is managing complexity. This is greatly aided by a design focus on simplicity.
• Simplicity is achieved in two general ways: minimizing the amount of essential complexity that anyone's brain has to deal with at any one time, and keeping accidental complexity from proliferating needlessly.
• Design is heuristic. Dogmatic adherence to any single methodology hurts creativity and hurts your programs.
• Good design is iterative; the more design possibilities you try, the better your final design will be.
• Information hiding is a particularly valuable concept. Asking "What should I hide?" settles many difficult design issues.
• Lots of useful, interesting information on design is available outside this book. The perspectives presented here are just the tip of the iceberg.

This section discusses issues related to containment, inheritance, member functions and data, class coupling, constructors, and value-vs.-reference objects.

• Class interfaces should provide a consistent abstraction. Many problems arise from violating this single principle.
• A class interface should hide something—a system interface, a design decision, or an implementation detail.
• Containment is usually preferable to inheritance unless you're modeling an "is a" relationship.
• Inheritance is a useful tool, but it adds complexity, which is counter to Software's Primary Technical Imperative of managing complexity.
• Classes are your primary tool for managing complexity. Give their design as much attention as needed to accomplish that objective.

What kinds of interface assumptions about parameters should you document? • Whether parameters are input-only, modified, or output-only • Units of numeric parameters (inches, feet, meters, and so on) • Meanings of status codes and error values if enumerated types aren't used • Ranges of expected values • Specific values that should never appear

• The most important reason for creating a routine is to improve the intellectual manageability of a program, and you can create a routine for many other good reasons. Saving space is a minor reason; improved readability, reliability, and modifiability are better reasons.
• Sometimes the operation that most benefits from being put into a routine of its own is a simple one.
• You can classify routines into various kinds of cohesion, but you can make most routines functionally cohesive, which is best.
• The name of a routine is an indication of its quality. If the name is bad and it's accurate, the routine might be poorly designed. If the name is bad and it's inaccurate, it's not telling you what the program does. Either way, a bad name means that the program needs to be changed.
• Functions should be used only when the primary purpose of the function is to return the specific value described by the function's name.
• Careful programmers use macro routines with care and only as a last resort.

Exceptions are a specific means by which code can pass along errors or exceptional events to the code that called it. If code in one routine encounters an unexpected condition that it doesn't know how to handle, it throws an exception, essentially throwing up its hands and yelling, "I don't know what to do about this—I sure hope somebody else knows how to handle it!"

• Production code should handle errors in a more sophisticated way than "garbage in, garbage out."
• Defensive-programming techniques make errors easier to find, easier to fix, and less damaging to production code.
• Assertions can help detect errors early, especially in large systems, highreliability systems, and fast-changing code bases.
• The decision about how to handle bad inputs is a key error-handling decision and a key high-level design decision.
• Exceptions provide a means of handling errors that operates in a different dimension from the normal flow of the code. They are a valuable addition to the programmer's intellectual toolbox when used with care, and they should be weighed against other error-processing techniques.
• Constraints that apply to the production system do not necessarily apply to the development version. You can use that to your advantage, adding code to the development version that helps to flush out errors quickly.

• Constructing classes and constructing routines tends to be an iterative process. Insights gained while constructing specific routines tend to ripple back through the class's design.
• Writing good pseudocode calls for using understandable English, avoiding features specific to a single programming language, and writing at the level of intent (describing what the design does rather than how it will do it).
• The Pseudocode Programming Process is a useful tool for detailed design and makes coding easy. Pseudocode translates directly into comments, ensuring that the comments are accurate and useful.
• Don't settle for the first design you think of. Iterate through multiple approaches in pseudocode and pick the best approach before you begin writing code.
• Check your work at each step, and encourage others to check it too. That way, you'll catch mistakes at the least expensive level, when you've invested the least amount of effort.

To summarize, following are the times a variable can be bound to a value in this example. (The details could vary somewhat in other cases.)

• Coding time (use of magic numbers)
• Compile time (use of a named constant)
• Load time (reading a value from an external source such as the Windows registry file or a Java properties file)
• Object instantiation time (such as reading the value each time a window is created)
• Just in time (such as reading the value each time the window is drawn)

The guiding principle is the Principle of Proximity: Keep related actions together.