Code Complete Contents Page 1 © Steven C. McConnell. All Rights Reserved. 1/12/2004 3:43 PM H:\BOOKS\codec2ed\Toc-Detailed.doc F RONT M ATTER Preface [Preface] Who Should Read This Book? Where Else Can You Find This Information? Key Benefits of This Handbook Why This Handbook Was Written Book Website Author Note Notes about the Second Edition [new] Acknowledgments [n/a] L AYING THE F OUNDATION Welcome to Software Construction [1] 1.1 What Is Software Construction? 1.2 Why Is Software Construction Important? 1.3 How to Read This Book Metaphors for a Richer Understanding of Software Development [2] 2.1 The Importance of Metaphors 2.2 How to Use Software Metaphors 2.3 Common Software Metaphors Measure Twice, Cut Once: Upstream Prerequisites [3] 3.1 Importance of Prerequisites 3.2 Determine the Kind of Software You’re Working On 3.3 Problem-Definition Prerequisite 3.4 Requirements Prerequisite 3.5 Architecture Prerequisite 3.6 Amount of Time to Spend on Upstream Prerequisites Key Construction Decisions [3+new material] 4.1 Choice of Programming Language 4.2 Programming Conventions 4.3 Your Location on the Technology Wave 4.4 Selection of Major Construction Practices C REATING H IGH Q UALITY C ODE Design in Construction [mostly new material, some from 7] 5.1 Design Challenges 5.2 Key Design Concepts 5.3 Design Building Blocks: Heuristics 5.4 Design Practices Code Complete Contents Page 2 © Steven C. McConnell. All Rights Reserved. 1/12/2004 3:43 PM H:\BOOKS\codec2ed\Toc-Detailed.doc 5.5 Comments on Popular Methodologies Working Classes [mostly new material, a little from 6] 6.1 Class Foundations: Abstract Data Types (ADTs) 6.2 Good Class Interfaces 6.3 Design and Implementation Issues 6.4 Reasons to Create a Class 6.5 Language-Specific Issues 6.6 Beyond Classes: Packages High-Quality Routines [5] 7.1 Valid Reasons to Create a Routine 7.2 Design at the Routine Level 7.3 Good Routine Names 7.4 How Long Can a Routine Be? 7.5 How to Use Routine Parameters 7.6 Special Considerations in the Use of Functions 7.7 Macro Routines and Inline Routines Defensive Programming [5.6 + new material] 8.1 Protecting Your Program From Invalid Inputs 8.2 Assertions 8.3 Error Handling Techniques 8.4 Exceptions 8.5 Barricade Your Program to Contain the Damage Caused by Errors 8.6 Debugging Aids 8.7 Determining How Much Defensive Programming to Leave in Production Code 8.8 Being Defensive About Defensive Programming The Pseudocode Programming Process [4+new material] 9.1 Summary of Steps in Building Classes and Routines 9.2 Pseudocode for Pros 9.3 Constructing Routines Using the PPP 9.4 Alternatives to the PPP V ARIABLES General Issues in Using Variables [10] 10.1 Data Literacy 10.2 Making Variable Declarations Easy 10.3 Guidelines for Initializing Variables 10.4 Scope 10.5 Persistence 10.6 Binding Time 10.7 Relationship Between Data Types and Control Structures 10.8 Using Each Variable for Exactly One Purpose Code Complete Contents Page 3 © Steven C. McConnell. All Rights Reserved. 1/12/2004 3:43 PM H:\BOOKS\codec2ed\Toc-Detailed.doc The Power of Variable Names [9] 11.1 Considerations in Choosing Good Names 11.2 Naming Specific Types of Data 11.3 The Power of Naming Conventions 11.4 Informal Naming Conventions 11.5 Standardized Prefixes 11.6 Creating Short Names That Are Readable 11.7 Kinds of Names to Avoid Fundamental Data Types [11] 12.1 Numbers in General 12.2 Integers 12.3 Floating-Point Numbers 12.4 Characters and Strings 12.5 Boolean Variables 12.6 Enumerated Types 12.7 Named Constants 12.8 Arrays 12.9 Creating Your Own Types Unusual Data Types [11.9, 10.6] 13.1 Structures 13.2 Pointers 13.3 Global Data S TATEMENTS Organizing Straight-Line Code [13] 14.1 Statements That Must Be in a Specific Order 14.2 Statements Whose Order Doesn’t Matter Using Conditionals [14] 15.1 if Statements 15.2 case Statements Controlling Loops [15] 16.1 Selecting the Kind of Loop 16.2 Controlling the Loop 16.3 Creating Loops Easily—from the Inside Out 16.4 Correspondence Between Loops and Arrays Unusual Control Structures [16] 17.1 Multiple Returns from a Routine 17.2 Recursion 17.3 goto 17.4 Perspective on Unusual Control Structures Code Complete Contents Page 4 © Steven C. McConnell. All Rights Reserved. 1/12/2004 3:43 PM H:\BOOKS\codec2ed\Toc-Detailed.doc Table-Driven Methods [12.2] 18.1 General Considerations in Using Table-Driven Methods 18.2 Direct Access Tables 18.3 Indexed Access Tables 18.4 Stair-Step Access Tables 18.5 Other Examples of Table Lookups General Control Issues [17] 19.1 Boolean Expressions 19.2 Compound Statements (Blocks) 19.3 Null Statements 19.4 Taming Dangerously Deep Nesting 19.5 A Programming Foundation: Structured Programming 19.6 Control Structures and Complexity C ODE I MPROVEMENTS The Software-Quality Landscape [23] 20.1 Characteristics of Software Quality 20.2 Techniques for Improving Software Quality 20.3 Relative Effectiveness of Quality Techniques 20.4 When to Do Quality Assurance 20.5 The General Principle of Software Quality Collaborative Construction [24] 21.1 Overview of Collaborative Development Practices 21.2 Pair Programming 21.3 Formal Inspections 21.4 Other Kinds of Collaborative Development Practices Developer Testing [25] 22.1 Role of Developer Testing in Software Quality 22.2 Recommended Approach to Developer Testing 22.3 Bag of Testing Tricks 22.4 Typical Errors 22.5 Test-Support Tools 22.6 Improving Your Testing 22.7 Keeping Test Records Debugging [26] 23.1 Overview of Debugging Issues 23.2 Finding a Defect 23.3 Fixing a Defect 23.4 Psychological Considerations in Debugging 23.5 Debugging Tools—Obvious and Not-So-Obvious Refactoring [Mostly new material; some from 30] Code Complete Contents Page 5 © Steven C. McConnell. All Rights Reserved. 1/12/2004 3:43 PM H:\BOOKS\codec2ed\Toc-Detailed.doc 24.1 Kinds of Software Evolution 24.2 Introduction to Refactoring 24.3 Reasons to Refactor 24.4 Specific Refactorings 24.5 Refactoring Safely 24.6 Refactoring Strategies Code-Tuning Strategies [28] 25.1 Performance Overview 25.2 Introduction to Code Tuning 25.3 Kinds of Fat and Molasses 25.4 Measurement 25.5 Iteration 25.6 Summary of the Approach to Code Tuning Code-Tuning Techniques [29] 26.1 Logic 26.2 Loops 26.3 Data Transformations 26.4 Expressions 26.5 Routines 26.6 Recoding in Assembler 26.7 The More Things Change, the More They Stay the Same S YSTEM C ONSIDERATIONS How Program Size Affects Construction [21] 27.1 Communication and Size 27.2 Range of Project Sizes 27.3 Effect of Project Size on Errors 27.4 Effect of Project Size on Productivity 27.5 Effect of Project Size on Development Activities Managing Construction [22, and some from 27.4] 28.1 Encouraging Good Coding 28.2 Configuration Management 28.3 Estimating a Construction Schedule 28.4 Measurement 28.5 Treating Programmers as People 28.6 Managing Your Manager Integration [27] 29.1 Importance of the Integration Approach 29.2 Integration Frequency—Phased or Incremental? 29.3 Incremental Integration Strategies 29.4 Daily Build and Smoke Test Code Complete Contents Page 6 © Steven C. McConnell. All Rights Reserved. 1/12/2004 3:43 PM H:\BOOKS\codec2ed\Toc-Detailed.doc Programming Tools [20] 30.1 Design Tools 30.2 Source-Code Tools 30.3 Executable-Code Tools 30.4 Tool-Oriented Environments 30.5 Building Your Own Programming Tools 30.6 Tool Fantasyland S OFTWARE C RAFTSMANSHIP Layout and Style [18] 31.1 Layout Fundamentals 31.2 Layout Techniques 31.3 Layout Styles 31.4 Laying Out Control Structures 31.5 Laying Out Individual Statements 31.6 Laying Out Comments 31.7 Laying Out Routines 31.8 Laying Out Classes Self-Documenting Code [19] 32.1 External Documentation 32.2 Programming Style as Documentation 32.3 To Comment or Not to Comment 32.4 Keys to Effective Comments 32.5 Commenting Techniques Personal Character [31] 33.1 Isn’t Personal Character Off the Topic? 33.2 Intelligence and Humility 33.3 Curiosity 33.4 Intellectual Honesty 33.5 Communication and Cooperation 33.6 Creativity and Discipline 33.7 Laziness 33.8 Characteristics That Don’t Matter As Much As You Might Think 33.9 Habits Themes in Software Craftsmanship [32] 34.1 Conquer Complexity 34.2 Pick Your Process 34.3 Write Programs for People First, Computers Second 34.4 Program Into Your Language, Not In It 34.5 Focus Your Attention with the Help of Conventions 34.6 Program in Terms of the Problem Domain 34.7 Watch for Falling Rocks Code Complete Contents Page 7 © Steven C. McConnell. All Rights Reserved. 1/12/2004 3:43 PM H:\BOOKS\codec2ed\Toc-Detailed.doc 34.8 Iterate, Repeatedly, Again and Again 34.9 Thou Shalt Rend Software and Religion Asunder Where to Find More Information [33] 35.1 Information About Software Construction 35.2 Topics Beyond Construction 35.3 Periodicals 35.4 A Software Developer’s Reading Plan 35.5 Joining a Professional Organization Code Complete Notes about the Second Edition Page i © 1993-2003 Steven C. McConnell. All Rights Reserved. 1/13/2004 2:40 PM H:\books\CodeC2Ed\Reviews\Web\-01-Preface2dEd.doc Notes about the Second 1 Edition 2 When I wrote Code Complete, First Edition, I knew that programmers needed a 3 comprehensive book on software construction. I thought a well-written book 4 could sell twenty to thirty thousand copies. In my wildest fantasies (and my 5 fantasies were pretty wild), I thought sales might approach one hundred thousand 6 copies. 7 Ten years later, I find that CC1 has sold more than a quarter million copies in 8 English and has been translated into more than a dozen languages. The success 9 of the book has been a pleasant surprise. 10 Comparing and contrasting the two editions seems like it might produce some 11 insights into the broader world of software development, so here are some 12 thoughts about the second edition in a Q&A format. 13 Why did you write a second edition? Weren’t the principles in the first 14 edition supposed to be timeless? 15 I’ve been telling people for years that the principles in the first edition were still 16 95 percent relevant, even though the cosmetics, such as the specific 17 programming languages used to illustrate the points, had gotten out of date. I 18 knew that the old-fashioned languages used in the examples made the book 19 inaccessible to many readers. 20 Of course my understanding of software construction had improved and evolved 21 significantly since I published the first edition manuscript in early 1993. After I 22 published CC1 in 1993, I didn’t read it again until early 2003. During that 10 23 year period, subconsciously I had been thinking that CC1 was evolving as my 24 thinking was evolving, but of course it wasn’t. As I got into detailed work on the 25 second edition, I found that the “cosmetic” problems ran deeper than I had 26 thought. CC1 was essentially a time capsule of programming practices circa 27 1993. Industry terminology had evolved, programming languages had evolved, 28 my thinking had evolved, but for some reason the words on the page had not. 29 After working through the second edition, I still think the principles in the first 30 edition were about 95 percent on target. But the book also needed to address new 31 content above and beyond the 95 percent, so the cosmetic work turned out to be 32 more like reconstructive surgery than a simple makeover. 33 Code Complete Notes about the Second Edition Page ii © 1993-2003 Steven C. McConnell. All Rights Reserved. 1/13/2004 2:40 PM H:\books\CodeC2Ed\Reviews\Web\-01-Preface2dEd.doc Does the second edition discuss object-oriented programming? 34 Object-oriented programming was really just creeping into production coding 35 practice when I was writing CC1 in 1989-1993. Since then, OO has been 36 absorbed into mainstream programming practice to such an extent that talking 37 about “OO” these days really amounts just to talking about programming. That 38 change is reflected throughout CC2. The languages used in CC2 are all OO 39 (C++, Java, and Visual Basic). One of the major ways that programming has 40 changed since the early 1990s is that a programmer’s basic thought unit is now 41 the classes, whereas 10 years ago the basic thought unit was individual routines. 42 That change has rippled throughout the book as well. 43 What about extreme programming and agile development? Do you talk 44 about those approaches? 45 It’s easiest to answer that question by first saying a bit more about OO. In the 46 early 1990s, OO represented a truly new way of looking at software. As such, I 47 think some time was needed to see how that new approach was going to pan out. 48 Extreme programming and agile development are unlike OO in that they don’t 49 introduce new practices as much as they shift the emphasis that traditional 50 software engineering used to place on some specific practices. They emphasize 51 practices like frequent releases, refactoring, test-first development, and frequent 52 replanning, and de-emphasize other practices like up-front planning, up-front 53 design, and paper documentation. 54 CC1 addressed many topics that would be called “agile” today. For example, 55 here’s what I said about planning in the first edition: 56 “The purpose of planning is to make sure that nobody 57 starves or freezes during the trip; it isn’t to map out each step 58 in advance. The plan is to embrace the unexpected and 59 capitalize on unforeseen opportunities. It’s a good approach 60 to a market characterized by rapidly changing tools, 61 personnel, and standards of excellence.” 62 Much of the agile movement originates from where CC1 left off. For example, 63 here’s what I said about agile approaches in 1993: 64 “Evolution during development is an issue that hasn’t 65 received much attention in its own right. With the rise of code- 66 centered approaches such as prototyping and evolutionary 67 delivery, it’s likely to receive an increasing amount of 68 attention.” 69 Code Complete Notes about the Second Edition Page iii © 1993-2003 Steven C. McConnell. All Rights Reserved. 1/13/2004 2:40 PM H:\books\CodeC2Ed\Reviews\Web\-01-Preface2dEd.doc “The word “incremental” has never achieved the 70 designer status of “structured” or “object-oriented,” so no 71 one has ever written a book on “incremental software 72 engineering.” That’s too bad because the collection of 73 techniques in such a book would be exceptionally potent.” 74 Of course evolutionary and incremental development approaches have become 75 the backbone of agile development. 76 What size project will benefit from Code Complete, Second Edition? 77 Both large and small projects will benefit from Code Complete, as will business- 78 systems projects, safety-critical projects, games, scientific and engineering 79 applications—but these different kinds of projects will emphasize different 80 practices. The idea that different practices apply to different kinds of software is 81 one of the least understood ideas in software development. Indeed, it appears not 82 to be understood by many of the people writing software development books. 83 Fortunately, good construction practices have more in common across types of 84 software than do good requirements, architecture, testing, and quality assurance 85 practices. So Code Complete can be more applicable to multiple project types 86 than books on other software development topics could be. 87 Have there been any improvements in programming in the past 10 years? 88 Programming tools have advanced by leaps and bounds. The tool that I described 89 as a panacea in 1993 is commonplace today. 90 Computing power has advanced extraordinarily. In the performance tuning 91 chapters, CC2’s disk access times are comparable to CC1’s in-memory access 92 times, which is a staggering improvement. As computers become more powerful, 93 it makes sense to have the computer do more of the construction work. 94 CC1’s discussion of non-waterfall lifecycle models was mostly theoretical—the 95 best organizations were using them, but most were using either code and fix or 96 the waterfall model. Now incremental, evolutionary development approaches are 97 in the mainstream. I still see most organizations using code and fix, but at least 98 the organizations that aren’t using code and fix are using something better than 99 the waterfall model. 100 There has also been an amazing explosion of good software development books. 101 When I wrote the first edition in 1989-1993, I think it was still possible for a 102 motivated software developer to read every significant book in the field. Today I 103 think it would be a challenge even to read every good book on one significant 104 topic like design, requirements, or management. There still aren’t a lot of other 105 good books on construction, though. 106 [...]... accept input, you drop in code that accepts real input Instead of having your program pretend to produce output, you drop in code that © 1993-2003 Steven C McConnell All Rights Reserved H:\books\CodeC2Ed\Reviews\Web\02-Metaphors.doc 1/13/2004 2:40 PM Code Complete 2 Metaphors for a Richer Understanding of Software Development 262 produces real output You add a little bit of code at a time until you... source code, is often the only accurate description of the software In many projects, the only documentation available to programmers is the code itself Requirements specifications and design documents can go out of date, but the source code is always up to date Consequently, it’s imperative that the source code be of the highest possible quality Consistent application of techniques for source -code improvement... Basic, or other similar languages Numerous code examples The book contains almost 500 examples of good and bad code I’ve included so many examples because, personally, I learn best from examples I think other programmers learn best that way too © 1993-2003 Steven C McConnell All Rights Reserved H:\books\CodeC2Ed\Reviews\Web\-02-Preface.doc 1/13/2004 2:40 PM Code Complete Preface 132 The examples are in... loose approach is appropriate for small software projects too, If you use the wrong design for 1000 lines of code, you can refactor or start over completely without losing much © 1993-2003 Steven C McConnell All Rights Reserved H:\books\CodeC2Ed\Reviews\Web\02-Metaphors.doc 1/13/2004 2:40 PM Code Complete 2 Metaphors for a Richer Understanding of Software Development Page 10 295 296 F02xx03 297 Figure... Determining how your code will be tested 81 ● Designing and writing classes and routines 82 ● Creating and naming variables and named constants 83 ● Selecting control structures and organizing blocks of statements 84 ● Unit testing, integration testing, and debugging your own code 85 ● Reviewing other team members’ low-level designs and code and having them review yours 87 ● Polishing code by carefully... carefully formatting and commenting it 88 ● Integrating software components that were created separately 89 ● Tuning code to make it smaller and faster 75 76 79 86 © 1993-2003 Steven C McConnell All Rights Reserved H:\books\CodeC2Ed\Reviews\Web\01-Welcome.doc 1/13/2004 2:40 PM Code Complete 1 Welcome to Software Construction Page 5 For an even fuller list of construction activities, look through the... and with fewer headaches © 1993-2003 Steven C McConnell All Rights Reserved H:\books\CodeC2Ed\Reviews\Web\-02-Preface.doc 1/13/2004 2:40 PM Code Complete 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 Preface Page iv Complete software-construction reference This handbook discusses general aspects of construction... software develops You plant the code seeds in the spring Farmer’s Almanac and the Great Pumpkin willing, you’ll have a bumper crop of code in the fall © 1993-2003 Steven C McConnell All Rights Reserved H:\books\CodeC2Ed\Reviews\Web\02-Metaphors.doc 1/13/2004 2:40 PM Code Complete 2 Metaphors for a Richer Understanding of Software Development Page 8 231 232 F02xx02 233 234 Figure 2-2 It’s hard to extend... project management, requirements, design, and testing The rush to study these newly identified areas has left code construction as the ignorant cousin of software development © 1993-2003 Steven C McConnell All Rights Reserved H:\books\CodeC2Ed\Reviews\Web\-02-Preface.doc 1/13/2004 2:40 PM Code Complete Preface 166 172 Discussions about construction have also been hobbled by the suggestion that treating... enough production code to appreciate the state of the practice I conceived this book as a full discussion of code construction— from one programmer to another 223 Book Website 214 215 216 217 218 219 220 221 224 CC2E.COM/ 1234 227 Updated checklists, recommended reading, web links, and other content are provided on a companion website at www.cc2e.com To access information related to Code Complete, 2d Ed., . size project will benefit from Code Complete, Second Edition? 77 Both large and small projects will benefit from Code Complete, as will business- 78 systems. 5.4 Design Practices Code Complete Contents Page 2 © Steven C. McConnell. All Rights Reserved. 1/12/2004 3:43 PM H:BOOKScodec2edToc-Detailed.doc