Table Of Content

Large-Scale C++ Software Design John Lakes • TT ADDISON·W ESLEY An imprint of Addison Wesley Longman, Inc. Reading, Massachusetts Harlow, England Menlo Park, California Berkeley, California Don Mills, Ontario Sydney Bonn Amsterdam Tokvo Mexico Citv The authors and publishers have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information of programs contained herein. The publisher offers discounts on this book when ordered in quantity for special sales. For more infonnation please contact: Corporate & Professional Publishing Group Addison-Wesley Publishing Company One Jacob Way Reading, Massachusetts 01867 Library of Congress Cataloging-in-Publication Data Lakos, John, 1959- Large-scale C++ software design / John Lakos. p. cm. -- (Addison-Wesley professional computing series) Includes bibliographical references and index. ISBN 0-201-63362-0 (pbk. : alk. paper) . 1. C++ (Computer program language) 2. Computer software -Development. I. Title. II. Series. QA7 6.73.C153L342 1996 005.13'3--dc20 95-52106 CIP DEDICATION iTo my parents, Marci ana gene, wfw preparea ana encouragea me. iTo my wife, Catliy, wfw suffered tlirougli it witli me. iTo my aaugliter, Sarafi, wlio was 60m in tlie mitfafe ofi t alr. Copyright © 1996 by Addison Wesley Longman, Inc. All rights reserved. No part of this publication may pe reproduced, stored in a retrieval system, or transmitted in any fonn or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission of the publisher. Printed in the United States of America. Published simultaneously in Canada. Text printed on recycled and acid-free paper ISBN 0-201-63362-0 3456789 10 11-MA-00999897 Third printing, January 1997 Contents Figure List ••• XIII Preface xxv Chapter 0: Introduction 1 0.1 From C to C++ .................................................................................... ............................ ,. ........... 2 ~ 0.2 Using C++ to Develop Large Projects ............................................................................... 2 0.2.1 Cyclic Dependencies .............................................................................................. 3 0.2.2 Excessive Link-Time Dependencies ....................................................................... 5 0.2.3 Excessive Compile-Time Dependencies ................................................................................ 7 0.2.4 The Global Name Space ................................................................................................ 10 ................................................. 0.2.5 Logical vs. Physical Design ............................................... . 12 ,. ..................................................................................................................................... 0.3 Reuse 14 ................................................................................................................................ 0.4 Quality 15 0.4.1 Quality Assurance ........................................................................•..•..•••••••••••••••••• 16 ................................................................................................. .0 .4.2 Quality Ensurarice 17 ................................................................................................ 0.5 Software Development Tools 17 ............................................................................................................................ 0.6 Summary 18 PART I: BASICS 19 Chapter 1: Preliminaries 21 1.1 Multi-File C++ Programs ........................................... .................................................... 21 ~ 1.1.1 Declaration versus Definition ............................................................................... 22 1.1.2 Internal versus External Linkage ...... :. .................................. ............................... 23 ~ • Contents VI 1.1.3 Header ( . h) Files .................................................................................................. 27 1.1.4 Implementation ( . c) Files .................................................................................... 29 1.2 t y p e de f Declarations ................. -.................................................................................... 30 : I, 1.3 Assert Statements ...... 32 ~ 1111 •••••••••••••••••••••••• •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• 1.4 A Few Matters of Style .................................................................................................... 33 1.4.1 Identifier Names ............................ 34 ~ 1111 ........................................ .............................. III ....................................................................................... 1.4.1.1 Type Names ............................................................................................ 34 1.4.1.2 Multi-Word Identifier Names ....... ,. ........................................................ 35 1.4.1.3 I:>£lt(l 1\Ilemller Names .............................................................................. 3(i 1.4.2 Class Member Layout ...................................... ,. ........... , ...................................... 38 1.5 _I t erators ................................................................................................................................................................... .............................. 40 ~ 1.(5 1'lotGltioIl ................................................................................................. 47 Lo~ic;Gtl I:>t!si~n 1.(5.1 TheIsARelation ..................................................................... .................. ............ 48 ~ ~ 1.(5.2 The Uses-In-The-Interface Relation ..................................................................... 50 1.(i.3 The U ses-In-The-Implemelltation Relation .......................................................... 52 1. (i. 3 .1 Uses ................ ............ 55 ~ ~ ~ ~ ~ l1li ...... ••••••••••••••••• ••••••••••• •• l1li •• ................................. 1.(5.3 .. 2 HasA and HoldsA .... ............................................................................... 5(i ~ 1.(i.3.3 Was A ......................................................................................................... 57 1.7 Inheritance versus Layering ............................................................................................ 58 1.8 Minimali ty ....................................................................................................................... 59 1.9 SlllIllIlary ......................................................................................................................... (51 Chapter 2: Ground Rules 63 2.1 Overview .................................................................................................... ..................... (53 ~ 2.2 Member I:>ata Access .............................................. .......................................................... (55 ~ 1rllt! <:1loilClI 1'lClmt! ..............................................................................•................... ()9 ~.3 ~I>Cl<:t! 2.3.1 <:1lobal I:>ata ....................................... ..................................................................... (59 ~ 2.3.2 Free .............. ............................................. _.. ....................................... 72 Flln~tiolls ~ 2.3.3 Ellumerations, Typedefs, alld Constant I:>ata ........................................................ 73 2.3.4 Preprocessor 1\Ila<:ros ............................................................................................ 75 2.3.5 N ames in Header Files ..................................................... _.. .............. ................... 77 ~ .. 2.4 Include <:1uards ................ .. .. .. . .. .. ........... _.. ............... _.. ............ _.. ........................................... 80 2.5 Redulldan.t Include Guards ............................................................ .................................. 82 ~ 2.(i ................................................................................................................ I:>o~llIIlentation 8~ 2.7 COIlventioIlS ....................................................................................... 91 Identifier-Namin~ 2.8 SummaI"Y ......................................................................................................................... 93 Contents vii PART II: PHYSICAL DESIGN CONCEPTS 97 Chapter 3: Components 99 3.1 Components versus Classe.s ............................................................................................. 99 3.2 Physical Design Rules .................................................................................................... 10 8 3.3 J[Jt}e DeIJen<isC=>1l Relation .............................................................................................. 12() 3.4 ImIJlie<i DeIJen<iellcy ......................................•................................................................ 127 3.5 Extractillg Actual DeIJell<iencies ................................................................................... 134 3.() ...................................................................................................................... ~1riellcislliIJ 1~(5 3.(5.1 Long-Distallce an<i ImIJlied DeIJenciency ......................................... 141 ~1riell<ishiIJ 3 .().2 all<i Frau<i .......................................................................................... 144 ~1riendshiIJ 3 .7 Summary ..................................................... .-. .. .. .. . .. .. . .. .. . .. .. . .. . .. . .. . .. . . .. .. .. . .. .. .. . . .. . .. .. .. . .. .. 147 Chapter 4: Physical Hierarchy . 149 4.1 A MetaIJhor for Software Testillg .................................................................................. 149 4.2 A ComIJlex Subsystem .................................................................................................. 151 4.3 J[Jt}e Difficulty ill Testing "Goo<i" Interfaces ................................................................. 155 4.4 Desigll for Testability .................................................................................................... 157 4.5 Testillg ill Isolation ........................................................................................................ 1(51 4.() Acyclic Pllysical DeIJendencies ..................................................................................... 1( )4 4.7 Level Numbers ................................................................................................................................................................................ 1( 5() 4.7.1 J[Jt}e Origin of Level Numbers ............................................................................ 1( 57 4.7.2 Using Level Numbers in Software ..................................................................... 1(59 4.8 Hierarchical an<i Incremental Testillg ............................................................................ 174 4.9 Testing a ComIJlex Subsystem ....................................................................................... 181 4.10 Testability versus Testing ............................................................................................. 183 4.11 Cyclic Physical Depen<iencies ...................................................................................... 184 4.12 Cumulative ComIJonent DeIJell<iency ........................................................................... 187 4.13 Physical Design Quality ............................................................................................... 193 4 .14 Summary ...................................................................................................................... 20 1 Chapter 5: Levelization 203 5.1 Some Causes of Cyclic Physical Depenciencies ............................................................ 204 5.1.1 Enhancement .................................................... 204 <II. 41. 41 •••••••• <II ........................... 11 .............. 5.1412 Convenience ................................................................................................................. 208 5 .1. Intrillsic IllterdeIJelldellcy .................................................................................... 213 ~ viii Contents 5.2 Escalation .................................................................. ................................................... 215 ~ ][)(!m()tioll ........... ......................................................................................................... 5.~ .~ ~ ~2S> 5.LJ ............................................................................................................ <=>}JaCJll~ Iloint~rs 2~~ 5.5 Dumb Data ................................................... ................................................................ 257 ~ 5.6 .................................................................. ,. ................................................. R~dllndancy ~69 5.7 Callbacks ....................................................................................................................... 275 5.8 Class ............................................................................................................... 288 Manag~r 5.S> Factoring ........................................................................................................................ 29LJ 5.10 Escalating Encapslliation .............................................................................................. 312 5.11 Sllmmary ...................................................................................................................... 3 2~ Chapter 6: Insulation 327 6.1 From Encapsulation to Insulation .................................................................................. ~28 6.1.1 The Cost of COll}Jling ................................................................. Com}Jil~-Tim~ ~~~ , 6.2 C++ Constructs and Time COll}Jling ............................................................... Com}Jil~- 3~5 6.2.1 Inheritance (IsA) and Com}Jile- COllpling .................................................. Tim~ 3~6 6.2.2 (HasA/HoldsA) and Time COll}Jling .................................... Lay~ring Com}Jil~- ~37 Fllnctions and COllpling ................................................... 6.2.~ Inlin~ Com}Jil~-Tim~ ~~9 6.2.4 and Time COllpling .................................................. 1 Privat~ Memb~rs Compi1~- ~~ 6.2.5 Members and Com}Jile-Time Cou}Jling .............................................. Prot~cted ~LJ2 6.2.6 Functions and Com}Jile-Time COll}Jling ............. 342 Compil~r-G~n~rat~d Memb~r 6.2. 7 and COll}Jling ................................................ Incllld~ Dir~ctiv~s Com}Jil~-Tim~ ~LJ4 and Compile- COllpling .............................................. 6.~.8 D~fallit Argllm~nts Tim~ 3~6 6.2.S> and COll}Jling ....................................................... 347 Enllm~rations Com}Jil~-Tim~ 6.:3 }>ClrtiClI IIlSlllCltioll ......................................................................................... T~clllli'llleS ~4S> 6.3.1 Ilrivate ............................................................................ 3LJ9 R~moving Inh~ritanc~ 6.:3.2 Removing DClta ................................................................. Embedd~d M~mbers ~52 Removing Ilrivate Functions ................................................................ 6.~.:3 Memb~r ~5~ 6.3.4 ........................................................................... R~moving Ilrotect~d M~mbers ~6~ 6.3.5 Removing Ilrivate Data ........................................................................ Memb~r ~75 Functions ......................................................... 6.~.6 R~moving Com}Jil~r-Gen~rat~d ~~8 6.:3. 7 Directives ............................................................................. R~moving Includ~ ~7S> RemoviIlg ............................................................................ 6.~.8 J:)~jfCllllt Argum~llts ~81 EnlllIlerCltions .................................................................................... :382 6.~.~ R~moving Total Insulation ........................................................................................... :3 85 6.~ T~chni'lu~s 6.4.1 The Protocol Class .............................................................................................. :386 Flllly Inslliatillg Class .................................................................. 6.~.2 Th~ Concret~ ~98 6.LJ.:3 InslllCltillg ...................................................................................... Tll~ ~r(l}J}J~r ~()5 . 406 Wrap}Jers .............................................................. . 6.~.~.1 Slngl~-Com}Jon~nt Multi-Component Wrap}Jers ................................................................ 415 6.~.3.2 • Contents IX 6.5 The Procedural Interface ............................................................................................................ 425 6.5.1 The Procedural Interface Architecture ............................................................... 426 6.5.2 Creating and Destroying Opaque Objects .......................................................... 428 ............................................................................................................... 42S> 6.5.~ ~an<lles 6.5.4 Accessing and Manipulating Opaque Objects .................................................... 4~5 6.5.5 Inheritance an<l Opaque Objects ......................................................................... 441 6.6 To Insulate or Not to Insulate ................................................................................................................................................. 445 6.6.1 The Cost of Insulation ........ 445 e .................................................................................. 6.6.2 1V\Tlten 1'l()t t() Inslll(lte ............................. ~ ............................................. ~ .............. 44~ t() IIlSlllClte ........•.......................................................................................... (i.(i.~ ~()~ 4:5~ (5.(i.4 1\Illlc;ll t() ........................................... ............................................ 4(i() ~()~ IIlSlllClt~ ~ 6.7 Summary ......................................................................................................................... 46~ Chapter 7: Packages 473 7.1 From Compollents to Packages ....................... .-............................................................. 474 7.2 Registere<l Package Prefixes .......................................................................................... 4~~ 7.2.1 The f()r Prefixes ......................................................................................... 1'l~~d 4~~ 7.2.2 Namespaces ........................................................................................................ 486 7.2.3 Preserving Prefix Integrity .................................................................................. 4S> 1 PCl<:1cClge ..................................................................................................... 7.~ ~eveli~Clti()Il 4~~ 7 The Importance of Packages ............................................................. 4S>4 .~.1 Leveli~ing PCl<:kClge 1rec;lliIlCjllt!S ....................................................................... 4S>6 7.~.2 ~eveli~Clti()Il 7 Partitiolling a System .......................................................................................... .~.3 4~8 7 Multi-Site Development ...................................................................................... 5()O .~.4 7.4 Package Insulation ......................................................................................................... 503 7.5 Pac1cage Groups ............................................................................................................. 5( )6 7.6 The s ............................................................................................................ 512 R~l~Cls~ Pr()c;~s 7.6.1 The Structure ......................................................................................... 514 R~leCls~ 7 .6.2 ................................................................................................................ 520 PCltch~s 7.7 Tile rna i J>r()gram ........................................................................................................ :;23 Yl 7.8 Start-Up ......................................................................................................................... 5~1 7.8.1 Initializati()Il Strategies ............................................. ,. ........................................ 5~4 7 The Wake-Up ..................................................... .~.1.1 Initiali~e<l1rechnique 5~4 7.8.1.2 The Explicit in it Function 1rechnique ............................................... 5~5 7. 1rhe Nifty Counter Technique ............................................................... 537 ~.1.~ 7.8.1.4 The Check-Every-1rime Technique ...................................................... 54~ 7.8.2 CleClIl-UI> ............................................................................................................ :54:; 7 Review ................................................................................................................ 546 .~.~ 7.9 Summary ........................................................................................................................ 546 x Contents PART III: LOGICAL DESIGN ISSUES 551 Chapter 8: Architecting a Component 553 8.1 Abstractions and Components ....................................................................................... 554 8.2 Component Interface Design ......................................................................................... 555 8'.3 Degrees of Encapsulation ............................ ................................................................... 560 ~ 8.4 Auxiliary Implementation Classes ................................................................................ 572 8.5 Summary ........................................................................... ........................................... 5,79 ~ Chapter 9: Designing a Function 583 9.1 Function Interface Specification ...........................................- ......................................... 584 9.1.1 Operator or Non-Operator Function ................................................................... 584 9.1.2 Free or Member Operator ................................................................................... 591 9.1.3 Virtual or Non-Virtual Function ......................................................................... 597 9.1.4 Pure or Non-Pure Virtual Member Function ...................................................... 603 9.1.5 Static or Non-Static Member Function ......, . ....................................................... 604 9.1.6 cons t Member or Non-con s t Member Function ............................................. 605 9.1.7 Public, Protected, or Private Member Function ................................................. 612 9.1.8 Return by Value, Reference, or Pointer ........................................................... 614 eo. 9.1.9 Return can s t or Non-co n s t ............................................................................ 618 9.1.10 Argument Optional or Required ........................................................................ 619 9.1.11 Pass Argument by Value, Reference, or Pointer ................................................ 621 9.1.12 Pass Argument as con s t or Non-c on s t ......................................................... 629 9.1.13 Friend or Non -Fri end Function ......................................................................... 630 9.1.14 Inline or Non-Inline Function ... 631 o.u ..................................................................... 9.2 Fundamental Types Used in the Interface ...................................................................... 633 9.2.1 Using s h art in the Interface ............ .-................................................................ 633 9.2.2 Using un s i 9 n ed in the Interface ....................................................................... 637 9.2.3 Using 1 on 9 in the Interface ................................................................................ 642 9.2.4 Using fl oa t, do b1 e, and 1 on 9 d au b1 e in the Interface ............................... 644 U 9.3 Special-Case Functions .................................................................................................. 645 9.3.1 Conversion Operators .................................................................................. '. ....... 646 9.3.2 Compiler-Generated Value Semantics ................................................................ 650 9.3.3 The Destructor .................................................................................................... 651 9.4 Summary ........................................................................................................................ 655 Chapter 10: Implementing an Object 661 10.1 Member Data ................ ...... ". .................. ., .... 662 ~ II .. I11 ........................ " ........................ 111 ...... 6 ........... 10.1.1 Natural Alignment ............................................................................................ 662 Contents • Xl 10.1.2 . Fundamental Types Used in the Implementation ............................................. 665 10.1.3 Using typedef in the Implementation ............................................................ 667 10.2 ][)efinitiolls ..................................................................................................... 6(5S) ~llnc;tioll 10.2.1 Assert Yourself! ................................................................................................ 66S) 10.2.2 Avoid Special Casing .......................•................................................................ 670 10.2.3 Fac;tor Instead of Duplic;ate .............................................................................. 673 10.2.4 Don't Be Too Clever ............................................................................................ 680 10.3 Memory Management .................... , .. , ........................................... ' ....... , ...................... 681 10.3.1 Logical versus Physical State Values ................................................................ 681 10.3.2 Physic;al Parameters .......................................................................................... 685 10. . 3.3 Memory Alloc;ators ........................................................................................... 6S)1 10.3.4 Class-Spec;ific; Memory .............................................................. 698 Mallagem~nt 10.3.4.1 Adding Custom Memory Management .............................................. 702 10.3.4.2 1r.Iogging Mem()ry ............................................................................... ~05 10.3.5 Obj ect- Spec;ific; Memory Management .................. , ......... ',' .............................. 711 10.4 Using C++ Templates ill Large Proj ects ..... ". ................................................................ 18 ~ 10.4.1 Compiler Implementations ............................................................................... 18 ~ 10.4.2 Managing Memory in Templates ...................................................................... 71 S) 10.4.3 Patterns versus Templates ..... , .......................... , ................................................ ~30 10.5 Summary 33 ~ ..................................................................................................................................................... l1li ......................................................................... Appendix A The Protocol Hierarchy 737 Illtent ..................................................................................................................................... ~:3S) Also Known As ..... ". .................................................................................................................. ~·3s) Motivation ...................................................... ,. ..................................................................... 73s) App lic;abili ty ......................................................................................................................... 44 ~ ~tlrLlc;tlIr~ ............................................................................................................................... ~~~ Participants ........................................................................................................................... 745 Collaborations ........................................................................................................................................... ~ ~6 Consequences ....................................................................................................................... 46 ~ IIlljJlt!IlleIltGlti()1l ..................................................................................................................... ~~~ Sample Code ......................................................................................................................... 61 ~ Known Uses ............ ................................................................................................................... 766 ~ Patterns .................................................................................................................................................... R~lat~d ~ 6~ xii Contents Appendix B Implementing an ANSI C-Compatible C++ Interface 769 B.l Memory Allocation Error Detection ............................................................................. 769 B.2 Providing a Main Procedure (ANSI COnly) ................................................................ 778 Appendix C A Dependency Extractor!A nalyzer Package 779 C.l Using adep, cdep, and 1 dep ......................................................................................7 80 C.2 DO(;UIIlentCltion ................................................................................... COIIlIIland-~in~ -79~ Idep Package Architecture ............................................................................................ 81 0 C.~ C.4 Source Code ................................................................................................................... 81~ AppendixD Quick Reference 815 D.l Definitions .................................................................................... ··. .. ". ............................ 815 ][).2 1\I.Iajor ][)esign ...................................................................................................... 82() ~ules Minor ][)esign Rules ...................................................................................................... 821 ][).~ ][).4 Guidelines .......................................................................................................................... 822 1:>.:; ~Ilc;iI>les ...................................................................................................................... 824 Bibliography 833 Index 835