Large-Scale C++ Software Design

John Lakes

•
TT
ADDISON· WESLEY
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.
QA76.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 of it 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
VI• Contents

1.1.3 Header ( . h) Files .................................................................................................. 27

1.1.4 Implementation ( . c) Files .................................................................................... 29
1.2 t y pe de f Declarations .................-.................................................................................... 30
: I,

1.3 Assert Statements ...... 1111 •••••••••••••••••••••••• ~ •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• 32

1.4 A Few Matters of Style .................................................................................................... 33
1.4.1 Identifier Names ............................ ~
1111 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 _Iterators ................................................................................................................................................................... ~ .............................. 40
1.(5 Lo~ic;Gtl I:>t!si~n 1'lotGltioIl ................................................................................................. 47
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 ................ ~ ............ ~ l1li . . . . . . ~ ~
••••••••••••••••• ~ 55 ••••••••••• • • 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 Minimality ....................................................................................................................... 59
1.9 SlllIllIlary ......................................................................................................................... (51

Chapter 2: Ground Rules 63

2.1 Overview .................................................................................................... ~ ..................... (53
2.2 Member I:>ata Access .............................................. ~ .......................................................... (55
~.3 1rllt! <:1loilClI 1'lClmt! ~I>Cl<:t! ..............................................................................•................... ()9
2.3.1 <:1lobal I:>ata ....................................... ~ ..................................................................... (59
2.3.2 Free Flln~tiolls .............. ~ ............................................. _......................................... 72
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 Identifier-Namin~ COIlventioIlS ....................................................................................... 91
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 .................................................................................................... 108
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 ~1riell<ishiIJ an<i ImIJlied DeIJenciency ......................................... 141
3 .().2 ~1riendshiIJ all<i Frau<i .......................................................................................... 144
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
41. 41 • • • • • • • • <II. <II . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 . . . . . . . . . . . . . .

5.1412 Convenience ................................................................................................................. 208

5.1. ~ Intrillsic IllterdeIJelldellcy .................................................................................... 213
viii Contents

5.2 Escalation .................................................................. ~ ...................................................215

5.~ ][)(!m()tioll .~ ........... ~ ......................................................................................................... ~2S>
5.LJ <=>}JaCJll~ Iloint~rs ............................................................................................................ 2~~
5.5 Dumb Data ................................................... ~ ................................................................ 257
5.6 R~dllndancy .................................................................. ,.................................................. ~69
5.7 Callbacks ....................................................................................................................... 275
5.8 Manag~r Class ............................................................................................................... 288
5.S> Factoring ........................................................................................................................ 29LJ
5.10 Escalating Encapslliation .............................................................................................. 312
5.11 Sllmmary ...................................................................................................................... 32~

Chapter 6: Insulation 327

6.1 From Encapsulation to Insulation .................................................................................. ~28
6.1.1 The Cost of Com}Jil~-Tim~ COll}Jling ................................................................. ~~~
, 6.2 C++ Constructs and Com}Jil~- Time COll}Jling ............................................................... 3~5
6.2.1 Inheritance (IsA) and Com}Jile- Tim~ COllpling .................................................. 3~6
6.2.2 Lay~ring (HasA/HoldsA) and Com}Jil~- Time COll}Jling .................................... ~37
6.2.~ Inlin~ Fllnctions and Com}Jil~-Tim~ COllpling ................................................... ~~9
6.2.4 Privat~ Memb~rs and Compi1~- Time COllpling .................................................. ~~ 1
6.2.5 Prot~cted Members and Com}Jile-Time Cou}Jling ..................... ......................... ~LJ2
6.2.6 Compil~r-G~n~rat~d Memb~r Functions and Com}Jile-Time COll}Jling ............. 342
6.2. 7 Incllld~ Dir~ctiv~s and Com}Jil~-Tim~ COll}Jling ................................................ ~LJ4
6.~.8 D~fallit Argllm~nts and Compile- Tim~ COllpling .............................................. 3~6
6.2.S> Enllm~rations and Com}Jil~-Tim~ COll}Jling ....................................................... 347
6.:3 }>ClrtiClI IIlSlllCltioll T~clllli'llleS ......................................................................................... ~4S>
6.3.1 R~moving Ilrivate Inh~ritanc~ ............................................................................ 3LJ9
6.:3.2 Removing Embedd~d DClta M~mbers ................................................................. ~52
6.~.:3 Removing Ilrivate Memb~r Functions ................................................................ ~5~
6.3.4 R~moving Ilrotect~d M~mbers ........................................................................... ~6~
6.3.5 Removing Ilrivate Memb~r Data ........................................................................ ~75
6.~.6 R~moving Com}Jil~r-Gen~rat~d Functions ......................................................... ~~8
6.:3. 7 R~moving Includ~ Directives ............................................................................. ~7S>
6.~.8 RemoviIlg J:)~jfCllllt Argum~llts ............................................................................ ~81
6.~.~ R~moving EnlllIlerCltions .................................................................................... :382
6.~ Total Insulation T~chni'lu~s ........................................................................................... :3 85
6.4.1 The Protocol Class .............................................................................................. :386
6.~.2 Th~ Flllly Inslliatillg Concret~ Class .................................................................. ~98
6.LJ.:3 Tll~ InslllCltillg ~r(l}J}J~r ...................................................................................... ~()5
.
6.~.~.1 Slngl~-Com}Jon~nt Wrap}Jers .............................................................. .406
6.~.3.2 Multi-Component Wrap}Jers ................................................................ 415
 •
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
6.5.~ ~an<lles ............................................................................................................... 42S>
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 ........ e .................................................................................. 445
6.6.2 1V\Tlten 1'l()t t() Inslll(lte ............................. ~ ............................................. ~ .............. 44~
(i.(i.~ ~()~ t() IIlSlllClte ........•.......................................................................................... 4:5~
(5.(i.4 ~()~ 1\Illlc;ll t() IIlSlllClt~ ........................................... ~ ............................................ 4(i()
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 1'l~~d f()r Prefixes ......................................................................................... 4~~
7.2.2 Namespaces ........................................................................................................ 486
7.2.3 Preserving Prefix Integrity .................................................................................. 4S> 1
7.~ PCl<:1cClge ~eveli~Clti()Il ..................................................................................................... 4~~
7 .~.1 The Importance of Leveli~ing Packages ............................................................. 4S>4
7.~.2 PCl<:kClge ~eveli~Clti()Il 1rec;lliIlCjllt!S ....................................................................... 4S>6
7 .~.3 Partitiolling a System .......................................................................................... 4~8
7 .~.4 Multi-Site Development ...................................................................................... 5()O
7.4 Package Insulation ......................................................................................................... 503
7.5 Pac1cage Groups ............................................................................................................. 5()6
7.6 The R~l~Cls~ Pr()c;~s s ............................................................................................................ 512
7.6.1 The R~leCls~ Structure ......................................................................................... 514
7 .6.2 PCltch~s ................................................................................................................ 520
7.7 Tile rna i Yl J>r()gram ........................................................................................................ :;23
7.8 Start-Up ......................................................................................................................... 5~1
7.8.1 Initializati()Il Strategies ............................................. ,......................................... 5~4
7 .~.1.1 The Wake-Up Initiali~e<l1rechnique ..................................................... 5~4
7.8.1.2 The Explicit in it Function 1rechnique ............................................... 5~5
7. ~.1.~ 1rhe Nifty Counter Technique ............................................................... 537
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 ns 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 hart in the Interface ............ .-................................................................ 633
9.2.2 Using un s i 9ned in the Interface ....................................................................... 637
9.2.3 Using 1 on 9 in the Interface ................................................................................ 642
9.2.4 Using fl oa t, do U b1 e, and 1 on 9 d au b1 e in the Interface ............................... 644
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 ~llnc;tioll ][)efinitiolls ..................................................................................................... 6(5S)
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 Mallagem~nt .............................................................. 698
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)
Applic;ability ......................................................................................................................... ~ 44
~tlrLlc;tlIr~ ............................................................................................................................... ~~~
Participants ........................................................................................................................... 745
Collaborations ........................................................................................................................................... ~ ~6
Consequences ....................................................................................................................... ~ 46
IIlljJlt!IlleIltGlti()1l ..................................................................................................................... ~~~
Sample Code ......................................................................................................................... ~ 61
Known Uses ............ ~ ................................................................................................................... 766
R~lat~d Patterns .................................................................................................................................................... ~ 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!Analyzer Package 779
C.l Using adep, cdep, and 1 dep ......................................................................................780
C.2 COIIlIIland-~in~ DO(;UIIlentCltion ................................................................................... -79~
C.~ Idep Package Architecture ............................................................................................ 81 0
C.4 Source Code ................................................................................................................... 81~

AppendixD
Quick Reference 815
D.l Definitions .................................................................................... ·... "............................. 815
][).2 1\I.Iajor ][)esign ~ules ...................................................................................................... 82()
][).~ Minor ][)esign Rules ...................................................................................................... 821
][).4 Guidelines .......................................................................................................................... 822
1:>.:; ~Ilc;iI>les ...................................................................................................................... 824

Bibliography 833

Index 835
 Figure List

0-1: Cyclically Dependent Components -4

0-2: Oversized, Heavy-Weight, Non-Reusable Stri ng Class 6
0-3: An Insidious Source of Compile-Time Coupling 8
0-4: Unnecessary Compile-Time Dependencies 10
0-5: Unnecessary Global Name Space Pollution 11
0-6: Typedefs in Class Scope Are Easy to Find 12
1-1: Some Definitions with Internal Linkage 24
1-2: Some Function Definitions with External Linkage 25
1-3: What Does and Does Not Belong in a Header File 28
1-4: Typedefs Are Not Type-Safe 31
1-5: Creator/Manipulator/Accessor Member Organization 38
1-6: Get/Set Member Organization 39
1-7: Trailing Data Member Organization 40
1-8: A Simple Integer Set Class 42
1-9: Trivial Driver Exercising In tSet Functionality 42
1-10: Infeasible Implementation of I n t Set Output Operator 43
1-11: Attempting to Add Iteration Capability to the Container Itself 43
1-12: Another Implementation of the I n t Set Output Operator 44
1-13: A Standard Iterator for the I ntSet Container 46
1-14: Which Names Should We Use? 46
1-15: I ntSet Output Operator Using Succinct Iterator Implementation 47
1-16: The IsA Relation 49
1-17: Notations Used to Indicate Derivation 50
1-18: The Uses-In-The-Interface Relation within the i ntset Component 52
1-19: Both Kinds of Uses Relations Within the i ntset Component 54
xiv Figure List

1-20: Croo k Uses J ud9e 56

1-21: 8attl eshi p RasA Tower and HoldsA Cannon 56
1-22: Ari zonaMemori al WasA Battl eshi p 57
1-23: Layering versus Multiple Inheritance 59
2-1: Poor Unencapsulating Rectangl e Class Interface 66
2-2: Better Encapsulating Rectangl e Class Interface 68
2-3: Logical Module Containing Global State Information 72
2-4: Various Constructs at File Scope in a Header File 79
2-5: Reconvergent Include Graph Causing Compile-Time Error 80
2-6: Accommodating Repeated Inclusion Using Include Guards 81
2-7: Typical Screen Composed of Many Widgets 83
2-8: Include Graph for One Component in Window System of Size N = 5 84
2-9: Typical Screen Component with Redundant Include Guards 86
2-10: Preprocessor Times with/without Redundant Include Guards 87
3-1: Logi~a1 versus Physical View of Several Components 102
3-2: Header File stack. h for a stack Component 104
3-3: Two Views of a stack Compone'nt 105
3-4: Driver stack. t. c for Component stack 107
3-5: Illegal Physical Partitioning of Logical Entities 109
3-6: Poor Physical Design Where bar. c Depends on f 00 • c Directly 116
3-7: Somewhat Better Physical Design Where bar. c Depends on f 00 • h 117
3-8: Indirect Compile-Time Dependency of st r. c on cha ra r ray. h 123
3-9: Abstract Representation of Component Dependency 123
3-10: Link-Time Dependency of word on cha ra rray 125
3-11: Abstract, Component-Level Dependency Diagram 126
3-12: The Uses Relation Often Implies a Compile-Time Dependency 127
3-13: Uses Relation Almost Always Implies a Link-Time Dependency 128
3-14: Logical Uses Relation Implying Component Dependency 129
3-15: Logical IsA and HasA Relations Implying Component Dependency 130
3-16: Intercomponent Logical Relationships 131
3-17: Component Diagram Showing Only Direct Dependencies 133
3-18: Transitive Closure of Direct Dependency Graph 133
3-19: Related Logical Entities in Distinct Components 142
3-20: Erroneously Inferred Dependency of stack on ba r 142
3-21: Acyclic Dependency of Free Operators on Classes 143
3-22: Cyclic Dependency of Member Operators on Classes 144
3-23: Example of Abusing Friendship 146
4-1: Example Problem for a Point-to-Point Router 152
4-2: Complete Header File for p2p_Router 153
4-3: Sketch of geom_Poi nt and geom_Po 1ygon Class Interfaces 153
4-4: Straightforward Driver for Point- To~Point Routing Problem 155
4-5: Design for Testability in Integrated Circuits 158
4-6: Fictitious Highly Test-Resistant IC Chip with Only Two Pins 161
4-7: Physical Dependency for a p2p_route r Implementation 162
4-8: Components with Acyclic Implied Dependencies 165
4-9: Acyclic versus Cyclic Physical Dependencies 166
4-10: Logic Circuits Without and With Feedback 167
4-11: Levelized Component Dependency Diagram 170
4-12: Independently Reusable Subsystems 171
4-13: Is This Design Levelizable? 172
4-14: Component/Class Diagram 173
4-15: Component Direct Dependency Diagram. 174
4-16: The Need for Individual Component Drivers 176
4-17: Hierarchical Testing Strategy 177
4-18: Analyzing a Layered Object for Testing Purposes 179
4-19: Defects Detectable Through Testing 181
4-20: Component Dependency Diagram for Point-to-Point Router 182
4-21: Two Mutually Dependent Components Treated as One 186
4-22: Computing Link-Time Cost for a Binary Tree of Dependencies 190
4-23: Relative Link Costs Associated with Incremental Testing 191
4-24: Link Cost for Balanced Binary Tree Hierarchy, N = 63 192
4-25: Cyclically Dependent Subsystem Architecture of Size 7 194
4-26: CCD for Various Component Hierarchies of Size 7 195
4-27: Dependency Graphs for Two Alternative Designs of a Subsystem 198
4-28: Computing the CCD of a Theoretical Balanced Tree of Size 11 199
4-29: Illustrating the Effects of Redundancy 200
5-1: Two Representations of a Box 204
5-2: Two Mutually Dependent Components 206
5-3: Two Components Still Mutually Dependent 207
5-4: Unlevelizable Design of a Shape Editor 209
5-5: Elided. h File for Component shape 210
5-6: Entire . c File for Component shape 211
5-7: Simple Graph Consisting of Nodes and Edges 213
5-8: Public Interface of node Component 214
5-9: Public Interface for an edge Component 214
5-10: Cyclicly Dependent node and edge Components 215
5-11: wi ndow Dominates rectangl e 216
5-12: Illustration of Dominance Property for Components 217
5-13: Adding a Dependency Can Cause a Change in Level Numbers 218
5-14: rectangl e Dominates wi ndow 219
xvi Figure List

5-15: Neither rectangl e Nor wi ndow Dominates the Other 221

5-16: Header File for New Component s hap e uti 1 222
5-17: Improved Design for Shape Editor 223
5-18a: Small Shape Hierarchy 3 Components, Small Editor 3 Components 225
5-18b: Small Shape Hierarchy 3 Components, Large Editor 30 Components 226
5-18c: Large Shape Hierarchy 30 Components, Small Editor 3 Components 227
5-18d: Large Shape Hierarchy 30 Components, Large Editor 30 Components 228
5-19: Employing Escalation to Break Cyclic Dependencies 230
5-20: Employing Demotion to Break Cyclic Dependencies 230
5-21: Two Geometric Utility Components: geomuti 1 and geomuti 12 231
5-22: Demoting Common Functionality Among Utility Classes 233
5-23: Employing Demotion to Reduce CCD 233
5-24: Poorly Factored System Architecture 234
5-25: New System Architecture After Demoting the Enumeration 235
5-26: Poorly Factored Runtime Database Architecture- 236
5-27: Result of Enhancing a Poor Design 237
5-28: Close-Up of Poor ParserlDataBase Subsystem Architecture 238
5-29: A More Maintainable System Architecture 239
5-30: Cyclicly Dependent Library Subsystem 240
5-31: Demoting Low-Levellnfonnation in the Library Subsystem 241
5-32: Demoting "Just" the Interface of the Repa rt Base Class 243
5-33: Adopting All Three Architectural Improvements 244
5-34: Independently Testable and Reusable Subsystems 245
5-35: More Independently Testable and Reusable Subsystems 246
5-36: General Repackaging Technique 246
5~37: Component u Does Not Use Type T In Name Only 249
5-38: Handle Class that Uses FaD in Name Only 251
5-39: Trivial Test Driver for handl e Component 251
5-40: ScreenlWidget Design Causing Cyclic Dependency 253
5-41: Class Wid get "Knows About" Container Class Sere e n 254
5-42: Modified Architecture for wi dget Component 255
5-43: Levelizable Component Dependency for wi dget and screen 256
5-44: Test Driver for wi dget Component in Isolation 256
5-45: Some Common Questions Asked at a Horse-Racing Track 258
5-46: Header for Top-Level Component track 259
5-47: Header for the Intermediate-Level Component rae e 260
5-48: Header for the Leaf-Level Component horse 260
5-49: ComponentJClass Diagram for Racetrack Subsystem 261
5-50: Modifications to Component track 263
5-51: Revised Component/Class Diagram for Racetrack Subsystem 264
 Figure List xvii

5-52: Circuit C Implemented in Terms of Two Gates, gO and 9 1 265

5-53: Partial Component/Class Diagram for Ci rcui t Implementation 266
5-54: Representing Connectivity Using Integer Indices 267
5-55: New Component/Class Diagram for Cire u i t Implementation 268
5-56: Two Ways to Implement an Object that Has a Name 270
5-57: Shap e Ana1y z e r Forced To Use Highly Coupled Shap e Subsystem 272
5-58: Reducing CCD by Using Redundant Data and Opaque Pointers 274
5-59: Using Function qsort to Sort a Collection of Poi nt Objects 276
5-60: Implementation of Callback Function Comparing Two Poi n t Objects 277
5-61: Using a Callback to Program q S 0 r t Comparison Behavior 278
5-62: Abstract Base Class for an Arbitrarily Ordered Point Collection 279
5-63: Using a Virtual Function as a Callback to Enable Factoring 280
5-64: Demoting the Interface to Implement a Callback 281
5-65: A BIG Problem 283
5-66: Escalating Planet Destruction to a Higher Level 284
5-67: Demoting P1 an e t 's Interface to a Lower Level 285
5-68: Installing a Redundant Callback 286
5-69: Using Callbacks to Enable Independent Testing 287
5-70: How Not to Implement ali s t Component 289
5-71: Lis t with Lin k that Recursively Deletes the Next Lin k 289
5-72: Lis t with Destructor that Iteratively Deletes Each Lin k 290
5-73: Node Uses Edge In Name Only 291
5-74: Problems Associated with Original Graph Design 292
5-75: Basic Architecture of Graph Subsystem 293
5-76: Factoring Out Independently Testable Implementation Details 295
5-77: Factoring Out Network-Independent Data 296
5-78: Factored Network-Independent node and edge Components 297
5-79: Reusing the Network-Independent Portion of a Node 297
5-80: Array of 25 Lots in our CondoComp 1ex Example 298
5-8 I: Illustrating Value Semantics in a Graph 299
5-82: Generic Pt r Bag Container and Specializations 300
5-83: Header File for Generic ptrbag Component 302
5-84: Implementation File for Generic ptrbag Component 303
5-85: Component Dependency for a Factored Graph Architecture 304
5-86: graph Component Header Defining Classes Gnode, Gedge, and Graph 305
5-87: An operator« for Graph Using Low-Level Iterators 306
5-88: Simple Test Driver Illustrating Usage of the graph Component 307
5-89: Actual Relationships Among Grap h, Gnod e, and Ge d 9 e 308
5-90: Implied Physical Coupling to Avoid Long-Distance Friendship 309
5-91: 9 rap h . c Implementation File for 9 rap h Component 311
xviii Figure List

5-92: Spheres of Encapsulation 313

5-93: New Individual Component gnode Defining Class Gnode 316
5-94: Ineffective Encapsulation by Concealing Header Files 317
5-95: Escalating Encapsulation Using a Wrapper Component 319
5-96: Encapsulating Wrapper Component for Graph Subsystem 322
5-97: Driver Illustrating Usage of New graph Wrapper Component 323
6-1: Fully Encapsulated Array-Based St a c k Implementation 329
6-2: Fully Encapsulated Linked-List-Based Sta c k Implementation 329
6-3: Illustration of a Compile-Time Coupled System 331
6-4: Experiment to Measure Compile-Time Cost 333
6-5: Empirical Cost of Compile-Time Coupling 334
6-6: Inheritance Cannot Be Insulated from Clients 337
6-7: Embedded, Layered Objects Are Not Insulated from Clients 338
6-8: Ways that Inlining Functions Reduce Insulation 340
6-9: Private Members Are Not Insulated. 342
6-10: Relying on Compiler-Generated Functions 343
6-11: Class Using Many Types in Its Interface 345
6-12: Simplified Implementation of Per son's Withdraw Function 346
6-13: Component Containing Common Definitions 348
6-14: Private Inheritance and Access Declaration 350
6-15: Using Layering Instead of Private Inheritance 351
6-16: Converting HasA to HoldsA to Improve Insulation 353
6-17: Making Private Member Functions Static Members 354
6-18: Converting Static Member Functions into Free Functions 355
6-19a: 1 i st. h File for Lis t Class with Private Member Functions 356
6-19b: 1 i st. c File for Lis t Class with Private Member Functions 358
6-20: Passing Private Information into Static Free Functions 359
6-21a: 1i st. h File for 1 i s t Component with Static Free Functions 360
6-21 b: 1 i st. c File for 1 i s t Component with Static Free Functions 362
6-22: Moving Static Free Functions to Another Component 363
6-23: S hap e Class with Protected Support for Derived-Class Authors 365
6-24: Derived Rectangl e Shape and the Implementation of Its Draw Member 366
6-25:ComponentiClass Diagram for Original Shape System 367
6-26: Component/Class Diagram for New Shape System 368
6-27: New Reusable scri be Component to Facilitate Drawing 369
6-28: New Implementation of Rectangl e: : Draw 370
6-29: Shap e Class with Protected Member Functions Removed 371
6-30: Car Base Class Containing Protected Member Functions 372
6-31: Extracting a Protocol for Car 373
6-32: Protocol and Partial Implementation for a Car 374
 Figure List xix

6-33: Removing Private Static Member Data 375

6-34: Component/Class Diagram for Factored Shape Subsystem 377
6-35: Protocol for a Shape 378
6-36: Insulating Class Using Many Types in Its Interface 380
6-37: A Class Containing Three Distinct Kinds of Enumeration 382
6-38: Alternative.Definitions for the Three Enumerations of Figure 6-37 384
6-39: Protocol for a File 387
6-40: Header for a File Manager Component 388
6-41: System Using a File Protocol 389
6-42: Using a Non-Insulating El em Base Class 390
6-43: Extracting a Protocol for Base Class E1em 391
6-45: New Insulating Protocol Component e 1 em 393
6-46: New Implementation Component e 1 emi mp 395
6-47: New Insulating Utility Component el emuti 1 396
6-48: Using the New Insulating E1 em Base Class 397
6-49: Component Containing a Non-Insulating Concrete Class 399
6-50: Component Containing a Partially Insulating Concrete Class 401
6-51: Component Containing a Fully Insulating Concrete Class 403
6-52: Component Dependency of Graph Wrapper from Figure 5-95 406
6-53: Header for Fully Insulating 9 ra ph Wrapper Component, graph. h 409
6-54: Fully Insulated Reimplementation of Node I d from Figure 5-95 410
6-55: Partially Insulated Reimplementation of Node I d from Figure 5-95 411
6-56: Almost Fully Insulated Reimplementation of graph graph. c 415
6-57: Complete Component/Class Diagram for stack and Its Wrapper 416
6-58: Fully Insulating stack Wrapper Interface pubs tack . h 417
6-59: Implementation of Fully Insulating stack Wrapper, pubstack. c 419
6-60: The Difficulty with Wrapping Individual Components 420
6-61: Two-Way Coupling Caused by the Uses Relation Among Wrappers 421
6-62: Creating an Insulating, Multi-Component Wrapper 423
6-63: Schematic Illustration of a Procedural Interface 427
6-64: Procedural Interface for Creating an Opaque Stack Object 428
6-65: The Ease of Corruption Memory in ANSI C 429
6-66: Object Diagram Illustrating pi _S t ac k Han d 1 e and St ac k Organization 430
6-67: A Manager Handle for Class Stack 431
6-68: Component/Class Diagram for a Procedural Interface with Handles 431
6-69: Procedural Interface Component pi _s t a c k 432
6-70: Usage Model for a Manager Stack Handle 433
6-71: Destructor for Manager Handle Destroys Its "Held" Object 434
6-72: Returning a User-Defined Type by Value 436
6-73: Providing a Procedural Interface for Objects Returned by Value 437
xx Figure List

6-74: Comparing U sagelEfficiency of Two Procedural Interface Models 438

6-75: Using Handles to Manage Dynamic Memory in C++ 439
6-76: An ANSI C-Compliant Procedural Interface Involving Handles 440
6-77: Using an ANSI C-Compliant Procedural Interface Involving Handles 441
6-78: Examples of Inheritance Relationships 441
6-79: Examples of Standard Conversion Functions 442
6-80: Transitivity of Conversions in Inheritance Hierarchy 443
6-81: Some Relative Costs of Access and Creation 447
6-82: When to Insulate a Widely Used Component 450
6-83: The Cost of Returning a Fully Insulating Poi n t Object 451
6-84: Base-Class Sol i d with Public and Protected Interface 455
6-85: Somewhat More Insulating Abstract Class Sol i d 459
6-86: Protocol Class Sol i d 460
6-87 Arbitrary Graph Consisting of 15 Nodes, Each of Degree 3 463
6-88: Test Driver for Measuring Runtime Efficiency of Graph Subsystems 465
6-89: Runtime Cost of Various Graph System Architectures 466
7 -1: High-Level Interpreter Architecture 475
7-2: A Simple Development Organization for Packages 477
7-3: Dependencies on Components in Other Packages 478
7-4: Two Different Views of a System 481
7-5: Even Proscribed Constructs at File Scope Require Prefixes 485
7-6: Using Namespaces to Resolve Name Conflicts Among Vendors 488
7-7: Link-Time Errors Resulting from Missing the stdc Package Library 490
7-8: Acyclic Package Depende~cies Provide Flexibility 495
7-9: Two Mutually Dependent Packages 496
7-10: Escalating Mutual Dependencies Between Packages 496
7 -11: Implied Cyclic Package Dependencies 497
7-12: Levelizable Component Hierarchy; Unlevelizable Package Hierarchy 498
7-13: Less Useful, Physically Partitioned System Compare with Figure 7-4 499
7-14: System of Packages and Their Physical Dependencies 501
7-15: Potential Package Development Assignments Across Sites 502
7-16: A Package Is a Logical and Potentially a Physical Abstraction 504
7 -17: A Large-System Architecture 507
7 -18: Package Organization of Core Database Group 508
7-19: Hypothetical Very Large System with DAG-Like Group Dependencies 511
7-20: A Development Directory Hierarchy for Package Groups 515
7-21: Compilation Time/Overhead Due to Multiple Include Directories 519
7-22: Minimizing a Client's C~st of Including Headers 520
7-23: Glossary-Generator Program 524
7-24: Insulating Interface for a Glossary-Generator Wrapper Component 526
 Figure List xxi

7-25: High-Level Glossary Generator Program Architecture 527

7-26: Fully Insulating Interpreter Component for Glossary Generator 528
7-27: A Standalone Main Driver for Glossary Generator and Interpreter 529
7-28: Initialization of Non-Local Static Variables at Start-Up 532
7-29: Module that Wakes Up Already Initialized 535
7-30: Providing a Component with an Explicit In; t Function 536
7-31: Using Nifty Counters to Ensure Initialization Before Use 538
7-32: Component/Class Diagram of System with Automatic Initialization 540
7-33: ax_Regi s t ra r Object Used to Register Records at Start-Up 541
7-34: Using ax_Regi strar to Register my_Record 542
7-35: Component/Class Diagram of System Using Explicit Initialization 543
7-36: Check Every Time and Initialize if Necessary 544
8-1 : Avoiding Logical Coupling 559
8-2: Example of Poor Encapsulation 561
8-3: Test Driver for Poor bad_Poi nt Interface 561
8-4: Two Implementation Strategies for a geom_Box Class 563
8-5a: Partially Encapsulating Interface Array A 564
8-5b: Naive Fully Encapsulating Interface Array B 565
8-5c: Alternate Fully Encapsulating Interface Array C 565
8-6: Experimental Poi ntArray Class Implementation 567
8-7: Experimental Poi ntA r ray "Reading" Driver 568
8-8: Relative Costs of Accessing a Poi ntArray Element 569
8-9: Experimental Po i n tAr ray "Writing" Driver 570
8-10: Relative Costs of Manipulating a Poi n tAr ray Element 570
8-11 a: Original File Scope Implementation of my _ Lin k A 573
8-11 b: Separate Component Implementation of my _L ink B 574
8-11c: Slave Class Implementation of my _ Lin k C 575
8-11d: Local Class Implementation of my _L ink D 575
8-11e: Nested Class Implementation of my _L ink E 576
8-12: Summary of VariOllS Auxiliary Class Implementation Advantages 577
8-13: Deciding Which Auxiliary Class Implementation to Use 579
9-1: Two Usage Models for an Integer Set Abstraction 585
9-2: Hypothetical Implementation of Fundamental Type daub 1e 588
9-3: Two Usage Models for a Generic Symbol Table Abstraction 590
9-4: Summary of Properties of Some Fundamental Operators 590
9-5: Result of Implementing 0 per a to r+= as a Free Function 592
9-6: Ambiguity Resulting from both Conversion Operators 594
9-7: Result of Implementing 0 per at 0 r== as a Member Function 596
9-8: Polymorphic Comparison of Shapes Using Free Operators 598
9-9: Implementation of Polymorphic Comparison for geom_C i rc 1 e 600
xxii Figure List

9-10: Forcing Default Behavior to Be Enabled Explicitly 604

9-11: The C++ Language Enforces Physical const-ness Only 606
9-12: Illustrating con s t-Correctness 607
9-13: Establishing con s t -Correctness Graphically see Figure 9-12 609
9-14: A const-Correct Implementation of te_Tree and te_Node 611
9-15: A const-CorrectImplementationofPointlterHandle and Pointlter 612
9-16: Four Ways to ~eturn a Value from a Function 615
9-17: 0 == Success for All Functions that Return Status 616
9-18: Factoring Common Constructor Code 620
9-19: Modifying Function Arguments via Writable References 623
9-20: Modifying Function Arguments Only via Writable Pointer 624
9-21: Nesting Functions that Return via Writable Pointer 624
9-22: Retaining the Address of a Reference Argument in a Function 627
9-23: Making the Need for an Lvalue Explicit 627
9-24: Result of Integral Promotion 634
9-25: Using s hart Integers in the Interface Bad Idea 634
9-26: Template Class Parameterized by short 636
9-27: Mixing i nt with uns i gned in Binary Expressions 637
9-28: Using uns i gned Integers in the Interface Bad Idea 638
9-29: Innocent Client Function to Print the Forward Moving Average 638
9-30: Test Driver for pri ntForwa rdMovi ngAverage Function 639
9-31: Driver Output for pri ntForwa rdMovi ngAverage Function 639
9-32: Comparing an uns i gned i n t Return Value Against a Negative in t Value 640
9-33: Using long Integers in the Interface 643
9-34: Mixing Types i nt and long 643
9-35: The Two Forms of User-Defined Conversion Operators in C++ 646
9-36: Sketch of Two-Dimensional d2_tabl e Component 647
9-37: Misusing the d2_tabl e Component 648
9-38: Misusing gr _Graph to Look Up a gr _Node by Name 649
9-39: Failing to Define at Least One Virtual Function Out of Line 653
10-1: Size and Natural Alignment of Various User-Defined Types 663
10-2: User-Defined Types with Holes 664
10-3: Using s h 0 r t in the Implementation 665
10-4: Inappropriate Use of un s i 9 ned and s h 0 r t in the Implementation 666
10-5: Using typedef to Specify Fixed Size in the Implementation 668
10-6: Testing a typedef 669
10-7: Commenting/Asserting an Internal Invariant 670
10-8: Avoiding Special-Case Code 672
10-9: Factoring Common Creator/Assignment Functionality 673
10-10: Partial Header for Basic Symbol-Table Abstraction 675
 Figure List xxiii

10-11: Implementing a Symbol Table Class 679

10-12: One Possible Implementation of a String Class 683
10-13: Header File for an Array-Based Stack Component 686
10-14: Implementation File for an Array-Based Stack Component 687
10-15: Using a Fixed GROW_S I ZE Instead of an Adaptive GROW_FACTOR 688
10-16: Trivial Performance "Stress" Test Driver for my_stack 689
10-17: Relative Performance for Various Physical Parameter Settings 690
10-18: Interface for Simple Block-Allocator Component 691
10-19: Implementation of Simple Block-Allocator Component 692
10-20: Trivial Development Test Driver with Instrumented new and del e t e 694
10-21: Output from Running Trivial Development Test Driver on My Machine 694
10-22a: A Pool Allocator Interface 697
10-22b: A Pool Allocator Implementation Using a Block Allocator 697
10-23: Interface File for Priority-Queue Component my_po; ntqueue 699
10-24: Implementation File for Priority-Queue Component my_po; ntqueue 701
10-25: Typical Customized Class-Specific Memory-Management Scheme 703
10-26: Trivial Performance "Stress" Test Driver for my_Po; ntQueue 704
10-27: Relative Performance for Various Values of CHUN K_S I ZE 705
10-28: Reusing the p ub_Poo 1 Allocator to Implement my_Poi ntOueueEnt ry 707
10-29: Subtle Undefined Behavior Resulting from Static Initialization 708
10-30: Typical Memory-Usage Pattern due to Class-Specific Allocation 709
10-31: Providing Some Automatic Clean-up for a Class-Specific Allocator 710
10-32: Conditionally Compiling Out Optimization to Detect Memory Leaks 717
10-33: Enabling Derivation from Arbitrary Parameter Types 720
10-34: Converting a Class to a Template Class see Figure 3.2 722
10-35a: Template stack Component Interface stack. h 726
10-35b: Template stack Component Implementation stack. c 729
B-1: A Memory Allocator Component Interface 770
B-2: Illustration of Allocation Error Detection Scheme 771
B-3: Implementation of pi _ s t ac k Functionality 773
B-4: Detecting Memory Allocation Programming Errors 774
B-5: Memory Allocator Component Implementation 777
 Preface

As a member of the IC Division at Mentor Graphics Corporation, I am fortunate

to have worked with many bright, talented software engineers, developing very large
systems.

Back in 1985, Mentor Graphics became one of the first companies to attempt a truly
large project in C++. Back then no one knew how to do that, and no one could have
anticipated the cost overruns, slipped schedules, huge executables, poor performance,
and incredibly expensive build times that a naive approach would inevitably produce.

Many valuable lessons were learned along the way-knowledge obtained through bit-
ter experience. There were no books to help guide the design process; object-oriented
designs on this scale had never before been attempted.

Ten years later, with a wealth of valuable experience under its belt, Mentor Graphics
has produced several large software systems written in C++, and in doing so has
paved the way for others to do the same without having to pay such a high price for
the privilege.

During my 13 years as a C (turned C++) Computer-Aided Design (CAD) software

developer, I have seen over and over again that planning ahead invariably produces a
higher-quality, more maintainable product. My emphasis at Mentor Graphics has been
on helping to ensure that quality is an integral part of the design process from the very start.
xxvi Preface

In 1990 I developed the graduate course "Object-Oriented Design and Programming"

at Columbia University. As the instructor of this course since 1991, I have had the
opportunity to share many of the insights that we at Mentor Graphics gained during
our industrial-strength software development efforts. Questions and feedback from
literally hundreds of graduate students and professional programmers have helped me
to crystallize many important concepts. This book is a direct result of that experience.
To my knowledge, this is the first text that identifies development and quality issues
that arise only in large C++ projects. I hope that this information will be as useful in
your work as it is in mine.

Audience

Large-Scale C++ Software Design was written explicitly for experienced C++ soft-
ware developers, system architects, and proactive quality-assurance professionals.
This book is particularly appropriate for those involved in large development efforts
such as databases, operating systems~ compilers, and frameworks.

Developing a large-scale software system in C++ requires more than just a sound
understanding of the logical design issues covered in most books on C++ program-
ming. Effective design also requires a grasp of physical design concepts that, although
closely tied to the technical aspects of development, include a dimension with which
even expert professional software developers may have little or no experience.

Yet most of the advice presented in this book also applies to small projects. It is typical
for a person to start with a small project and then begin to take on larger and more
challenging enterprises. Often the scope of a p.articular project will expand, and what
starts out as a small project becomes a major undertaking. The immediate conse-
quences of disregarding good practice in a large project, however, are far more severe
than they are for disregarding good practice in a smaller project.

This book unites high-level design concepts with specific c++ programming details
to satisfy two needs:

I. An object-oriented design book geared specifically to practical aspects of

the c++ programming language.

2. A C++ programming book describing how to use the C++ programming

language to develop very large systems.
 Exampl~s in this Text xxvii

Make no mistake, this is an advanced text. This is not the book from which to learn
C++ syntax for the first time, nor is it likely to expose you to the dark corners of the
language. Instead, this book will show you how to use the full power of the C++ lan-
guage in ways that scale well to very large systems.

In short, if you feel that you know C++ well, but would like to understand more about
how to use the language effectively on large projects, this book is for you.

Examples in this Text

Most people learn by example. In general, I have supplied examples that illustrate
real-world designs. I have avoided examples that illustrate one point but have blatant
errors in other aspects of the design. I have also tried to avoid examples that illustrate
a detail of the language but serve no other usef~l purpose.

Except where otherwise indicated, all examples in this text are intended to represent
"good design." Examples presented in earlier chapters are therefore consistent with
all practices recommended throughout the book. A disadvantage of this approach is
that you may see code that is written differently from the code you are used to seeing,
without yet knowing exactly why. I feel that being able to use all of the examples in
the book for reference compensates for this drawback.

There are two notable exceptions to this practice: comments and 'package prefixes.
Comments for many of the examples in this text have simply been omitted for lack of
space. Where they are presented, they are at best minimal. Unfortunately, this is one
place where the reader is asked to "do as I say, not as I do"-at least in this book. Let
the reader be assured that in practice I am scrupulous about commenting all interfaces
as I write them (not after).

The second exception is the inconsistent use of package prefixes in the early examples
of the book. In a large project environment package prefixes are required, but they are
awkward at first and take some getting used to. I have elected to omit the consistent use
of registered package prefixes until after they are formally presented in Chapter 7, so as
not to detract from the presentation of other important fundamental material.

Many texts note that inline functions are used in examples for textual brevity when
illustrating intended functionality. Since much of this book is directly related to orga-
nizational issues such as when to inline, my tendency will be to avoid inline functions
xxviii Preface

in examples. If a function is declared i n 1 i n e, there is a justification for it beyond

notational convenience.

Developing large systems in C++ is a constant series of engineering trade-offs. There

are almost no absolutes. It is tempting to make statements using words such as never
and always. Such statements allow for a simplified presentation of the material. For
the level of C++ programmers whom I expect will read this book, such sweeping
statements would be challenged-and rightly so. To avoid getting side-tracked in such
situations, I will state what is (almost) always true, and then provide a footnote or a
pointer to the exceptional case.

There are a variety of popular file name extensions used to distinguish C++ header
files and C++ implementation files. For example:

Header File Extensions: .h • hxx . H . h++ . hh . hPP

Implementation File Extensions: .c .cxx .c . c++ .cc .cpp

Throughout the examples we consistently use the . h extension to identify C++ header
files and the . c extension to identify C++ implementation files. In the text, we will
frequently refer to header files as . h files and to implementation files as . c files.
Finally, all of the examples in this text have been compiled and are syntactically
correct using SUN'S version of CFRONT 3.0 running on SUN SPARC stations, as well as
on HP700 series machines running their native C++ compiler. Of course, any errors are
the sole responsibility of the author.

A Road Map

There is a lot of material to cover in this book. Not all readers will have the same
background. I have therefore provided some basic (but essential) material in Chapter
1 to help level the field. Expert C++ programmers may choose to skim this section or
simply refer to it if needed. Chapter 2 contains a modest collection of software design
rules that I would hope every experienced developer will quickly ratify.

Chapter 0: Introduction.
An overview of what lies in wait for the large-scale C++ software
developer.
 •
A Road Map XXIX

PART I: BASICS

Chapter 1: Preliminaries.
A review of basic language information, common design patterns, and
style conventions used in this book.

Chapter 2: Ground Rules.

Important design practices that should be followed in any C++ project.

The remainder of the text is divided into two main sections. The first, entitled "Physical
Design Concepts," presents a sequence of important topics related to the physical
structure of large systems. The material in these chapters (3 through 7) focuses on
aspects of programming that will be entirely new to many readers, and cuts right to
the bone of large program design. This section is presented "bottom up," with each
chapter drawing on information developed in previous chapters.

PART II: PHYSICAL DESIGN CONCEPTS

Chapter 3: Components.
The fundamental physical building blocks of a system.

Chapter 4: Physical Hierarchy.

The importance of creating a hierarchy of components with acyclic
physical dependencies for testing, maintainability, and reuse.

Chapter 5: Levelization.
Specific techniques for reducing link-time dependencies.

Chapter 6: Insulation.
Specific techniques for reducing compile-time dependencies.

Chapter 7: Packages.
Extending the above techniques to yet larger systems.

The final section, entitled "Logical Design Issues," addresses the conventional
discipline of logical design in conjunction with physical design. These chapters (8
through 10) address the design of a component as a whole, summarize the myriad
xxx Preface

issues surrounding sensible interface design, and address implementation issues in the
context of a large-project environment.

PART III: LOGICAL DESIGN ISSUES

Chapter 8: Architecting a Component.

An overview of considerations important to the overall design of
components.

Chapter 9: Designing a Function .

.A detailed survey of the issues involved in creating a component's
functional interface.

Chapter 10: Implementing an Object.

Several organizational issues specific to the implementation of
objects in a large-project environment.

Topics found in the appendixes are referenced throughout the text.

Acknowledgments

This book would not have been possible without the diligence of my many colleagues
at Mentor Graphics who have contributed to the company's landmark architectural
and development efforts.

First and foremost, I would like to recognize the contributions of my friend, col-
league, and former college classmate Franklin Klein, who reviewed virtually every
page of the manuscript in its raw form. Franklin provided a sounding board for pre-
senting many concepts that will be new to most software developers. The depth of
Franklin's wisdom, intelligence, knowledge, diplomacy, and grasp of the nuances of
effective communication is unprecedented in my experience. His detailed comments
are responsible for countless revisions in the content, flow, and demeanor of the pre-
sentation.

Several dedicated and gifted software professionals reviewed all or most of the mate-
rial in this book during its formative stages. I consider myself fortunate that they
agreed to invest their valuable time reviewing this book. I would like to thank Brad
Appleton, Rick Cohen, Mindy Garber, Matt Greenwood, Amy Katriel, Tom
 Acknowledgments xxxi

O'Rourke, Ann Sera, Charles Thayer, and Chris Van Wyk for the enormous energy
they spent helping to make this book as valuable as it could be. In particular, I would
like to thank Rick Eesley for many fertile discussions and practical recommenda-
tions especially his plea for a summary at the end of each chapter.

Several expert software developers and quality assurance engineers reviewed individ-
ual chapters. I would like to thank Samir Agarwal, Jim Anderson, Dave Arnone, Rob-
ert Brazile, Tom Cargill, Joe Cicchiello, Brad Cox, Brian Dalio, Shawn Edwards, Gad
Gruenstein, William Hopkins, Curt Horkey, Ajay Kamdar, Reid Madsen, Jason Ng,
Pete Papamichael, Mahesh Ragavan, Vojislav Stojkovic, Clovis Tondo, Glenn Wikle,
Steve Unger, and John Vlissides for their technical contributions. I would also like to
thank Lisa Cavaliere-Kaytes and Tom Matheson of Mentor Graphics for their sugges-
tions regarding some of the figures in this text. In addition I would like to acknowl-
edge the contributions of Eugene Lakos and Laura Mengel.

Since the original printing of this book, I would like to thank the following readers for
.helping me to remove some of the inevitable errors for which I take full responsibility:
Jamal Khan, Oat Nguyen, and Scott Meyers.

This book might never have been written were it not for a promotional letter I
received at Columbia University offering me a complimentary review copy of Rob
Murray's book. Since 1 teach only during the Spring semester, 1 returned the enclosed
form, but requested that the book be sent to Mentor Graphics instead of Columbia.
Soon after that, I received a call from Pradeepa Siva (of Addison-Wesley's Corporate
& Professional Publishing Group) determined to get to the bottom of this unusual
request. After convincing her of its legitimacy (and some perhaps gratuitous self
aggrandizement) she remarked, "I think my boss would like to talk with you." A few
days after that, 1 met with her boss-the publisher. 1 had always revered the excel-
lence of the Professional Computing Series produced by this group, and it is that rep-
utation that ultimately compelled me to commit to writing this book for that series.

lowe a great deal to the members of the Corporate & Professional Publishing Group
at Addison-:Wesley. John Wait, its publisher, has patiently provided me with insights
into people and communication that 1 will forever cherish. From relentlessly reading
books and reviews, to direct discussions with individual software professionals, to
standing in bookstores and discretely observing the buying habits of potential readers,
John Wait has his fingers on the pulse of the industry.
xxxii Preface

The production staff headed by Marty Rabinowitz is dedicated to excellence in all its
respects. Despite apprehension expressed to me by authors in academia (associated
with other publishers), I was delighted with the tremendous importance placed by
Marty on delivering a technically accurate, readily usable, and aesthetically appealing
rendering of the author's ideas. I especially want to thank Frances Scanlon for her tire-
less and seemingly endless efforts in typesetting this entire book.

Brian Kernighan, the technical editor of this series, provided valuable contributions
on both style and substance, as well as finding many typographical errors and incon-
sistencies that no one else caught. The depth and breadth of his knowledge coupled
with his concise writing style has in no small way contributed to the success of this
.
senese

Finally, I would like to thank the other authors in this series for documenting funda-
mental logical concepts and design practices that this book takes for granted.
 Introduction

Developing good C++ programs is not easy. Developing highly reliable and maintain-
able software in C++ becomes even more difficult and introduces many new concepts
as projects become larger. Just as experience gained from building single-family
homes does not qualify a carpenter to erect a skyscraper, many techniques and prac-
tices learned through experiences with smaller C++ projects simply do not scale well
to larger development efforts.

This book is about how to design very large, high-quality software systems. It is
intende~ for experienced C++ software developers who strive to create highly main-
tainable, highly testable software architectures. This book is not a theoretical
approach to programming; it is a thorough, practical guide to success, drawing from
years of experience of expert C++ programmers developing huge, multi-site systems.
We will demonstrate how to design systems that involve hundreds of programmers,
thousands of classes, and potentially millions of lines of C++ source code.

This introduction considers some of the kinds of problems encountered when devel-
oping large projects in C++, and provides a context for the groundwork we must do
in the early chapters. In this introduction several terms are used without definition.
Most of these terms should be understandable from context. In the chapters that fol-
low, these terms are defined more precisely. The real payoff will come in Chapter 5,
where we begin to apply specific techniques to reduce the coupling (i.e., the degree
of interdependency) within our C++ systems.
2 Introduction Chapter 0

0.1 From C to C++

The potential advantages of the object-oriented paradigm in managing the complexity

of large systems are widely assumed. As of the writing of this book, the number of
C++ programmers has been doubling every seven to nine months. 1 In the hands of
experienced C++ programmers, C++ is a powerful amplifier of human skill and engi-
neering talent. It is completely wrong, however, to think that just using C++ will
ensure success in a large project.

C++ is not just an extension of C: it supports an entirely new paradigm. The object-
oriented paradigm is notorious for demanding more design effort and savvy than its
procedural counterpart. C++ is more difficult to master than C, and there are innu-
merable ways to shoot yourself in the foot. Often you won't realize a serious error
until it is much too late to fix it and still meet your schedule. Even relatively small
indiscretions, such as the indiscriminate use of virtual functions or the passing of
user-defined types by value, can result in perfectly correct C++ programs that run ten
times slower than they would have had you written them in C.

During the initial exposure to C++, there is invariably a period during which produc-
tivity will grind to a halt as the seemingly limitless design alternatives are explored.
During this period, conventional procedural programmers will· be filled with an
uneasiness as they try to get their arms around the concept referred to as object
oriented.

Although the size and complexity of the C++ language can at first be somewhat over-
whelming for even the most experienced professional C programmers, it does not take
too long for a competent C programmer to get a small, nontrivial C++ program up and
running. Unfortunately, the undisciplined techniques used to create small programs in
C++ are totally inadequate for tackling larger projects. That is to say, a naive application
of C++ technology does not scale well to larger projects. The consequences for the
uninitiated are many.

0.2 Using C++ to Develop Large Projects

Just like a program in C, a poorly written C++ program can be very hard to under-
stand and maintain. If interfaces are not fully encapsulating, it will be difficult to tune

1 stroostrup94, Section 7.1, pp. 163-164.

Section 0.2.1 Cyclic Dependencies 3

or to enhance implementations. Poor encapsulation will hinder reuse, and any

advantage in testability will be eliminated.

Contrary to popular belief, object-oriented programs in their most general form are
fundamentally more difficult to test and verify than their procedural counterparts. 2
The ability to alter internal behavior via virtual functions can invalidate class invari-
ants essential to correct performance. Further, the potential number of control flow
paths through an object-oriented system can be explosively large.

Fortunately, it is not necessary to write such arbitrarily general (and untestable)

object-oriented programs. Reliability can be achieved by restricting our use of the par-
adigm to a more testable subset.

As programs get larger, forces of a different nature come into play. The following sub-
sections illustrate specific instances of some of the kinds of problems that we are
likely to encounter.

0.2.1 Cyclic Dependencies

As a software- professional, you have probably been in a situation where you were
looking at a software system for the first time and you could not seem to find a rea-
sonable starting point or a piece of the system that made sense on its own. Not being
able to understand or use any part of a system independently is a symptom of a cycli-
cally dependent design. C++ objects have a phenomenal tendency to get tangled up in
each other. This insidious form of tight physical coupling is illustrated in Figure 0-1. A
circuit is a collection" of elements and wires. Consequently, class Cire u i t knows
about the definitions of both E1 ement and Wi reo An element knows the circuit to
which it belongs, and can tell whether or not it is connected to a specified wire. Hence
class E1 ement also knows about both Ci rcui t and Wi reo Finally, a wire can be con-
nected to a terminal of either an element or a circuit. In order to do its job, class Wi re
must access the definitions of both E1 ement and Ci rcui t.

The definitions for each of these three object types reside in separate physical compo-
nents (translation units) in order to improve modularity. Even though the implementa-
tions of these individual types are fully encapsulated by their interfaces, however, the
. c files for each component are forced to include the header files of the other two. The

2 perry, pp. 13-19.

4 Introduction Chapter 0

resulting dependency graph for these three components is cyclic. That is, no one com-
ponent can be used or even tested without the other two.

II circuit.h
I I .. .
. .•. •. class Wi re;

class Circuit {
/ I ...
Wire *addWire(const char*);
Wire *addElem(const char*);

II circuit.c
#include "circuit.h"
#include "wire.h"
II element.h #include "element.h"
II ... /! ...

class Circuit;
class Wire;

class Element
I I ...
Circuit *getParent();
int isConn(const Wire&);

II e1ement.c
. . i}include "element.h" class Element;
'. #include »circuit.h H
class Circuit;
#include "wire.h"
/ I ...
class Wire
element / I ...
void conn(Element*~int term);
void connCCircuit*,int term);
. ..
II wire.c
#include "wire.h"
- -......- -____...,-,Fil iti ncl ude "el ement. hI!
#include "circuit.h"
/ I ...

wire

Figure 0-1: Cyclically Dependent Components

Large systems that are naively architected tend to become tightly coupled by cyclic
dependencies and fiercely resist decomposition. Supporting such systems can be a
nightmare, and effective modular testing is often impossible.
Section 0.2.2 Excessive Link-Time Dependencies 5

A case in point is an early version of an electronic-design database. At the time, its

authors did not realize the need for avoiding cyclic dependencies in the physical
design. The result was an interdependent collection of files containing hundreds of
classes with thousands of functions, and no way to use or even test it except as a sin-
gle module. This system had very poor reliability, proved impractical to extend or
maintain, and ultimately had to be thrown out and rewritten from scratch.

By contrast, hierarchical physical designs (i.e., without cyclic interdependencies) are

relatively easy to understand, test, and reuse incrementally.

0.2.2 Excessive Link-Time Dependencies

If you have attempted to link to a small amount of functionality in a library and

found that your time to link has increased disproportionately to the benefit you are
deriving, then you may have been trying to reuse heavy-weight rather than light-
weight components.

One of the nice things about objects is that it is easy to add missing functionality as the
need presents itself. This almost seductive feature of the paradigm has tempted many
conscientious developers to tum lean, well-thought-out classes into huge dinosaurs
that embody a tremendous amount of code-most of which is unused by the vast
majority of its clients. Figure 0-2 illustrates what can happen when the functionality in
a simple St r i n9 class is allowed to grow to fill the needs of all clients. Each time a
new feature is added for one client, it potentially costs all of the rest of the clients in
terms of increased instance size, code size, runtime, and physical dependencies.

c++ programs are often larger than necessary. If care is not taken, the executable size
for a C++ program could be much larger than it would be if the equivalent program
were written in C. By ignoring external dependencies, overly ambitious class develop-
ers have created sophisticated classes that directly or indirectly depend on enormous
amounts of code. A "Hello World" program employing one particularly elaborate
St r i n9 class produced an executable size of 1.2 megabytes!
6 Introduction Chapter 0

II str.h II str.c
#ifndef INCLUDED STR Hinclude IIstrohl!
#define INCLUDED_STR #include IIsun.h"
#include "moon.h"
class String { #include "stars.hl!
char *d_string_p; Ir ...
int d_length; II (lots of dependencies omitted)
int d size; I I ...
int d_count; #include "everyone.h"
I I .. 0 #include "theirbrother.h"
double d_creationTime; String::StringC)
d_string_p(O)
public: , d_length(O)
String(); , d_size(O)
String(const String& s); , d_count(O)
String(const char *cp); II
String(const char c); II
II .00 II
--String();
String &operator=(const String& s);
String &operator+=(const String& s);
II
II (27 pages omitted!)
I I ...
int isPalindrome() const;
int isNameOfFamousActor() const;
};

II

#endif

Figure 0-2: Oversized, Heavy-Weight, Non-Reusable Stri ng Class

Section 0.2.3 Excessive Compile-Time Dependencies 7

Overweight types such as this St r i n 9 class not only increase executable size but can
make the linking process unduly slow and painful. If the time necessary to link in
5 t r i n9 (along with all of its implementation dependencies) is large relative to the
time it would otherwise take to link your subsystem, it becomes less likely that you
would bother to reuse St r i n g.

Fortunately,. techniques exist for avoiding these and other forms of unwanted link-
time dependencies.

0.2.3 Excessive Compile-Time Dependencies

If you have ever tried to develop a multi-file program in C++, then you know that
changing a header file can potentially cause several translation units to recompile. At
the very early stages of system development, making a change that forces the entire
system to recompile presents no significant burden. As you continue to develop your
system, however, the idea of changing a low-level header file becomes increasingly
distasteful. Not only is the time necessary to recompile the entire system increasing,
but so is the time to compile even individual translation units. Sooner or later, there
comes a point where you simply refuse to modify a low-level class because of the cost
of recompiling. If this sounds familiar, then you may have experienced excessive
compile-time dependencies.

Excessive cornpile-:-time coupling, which is virtually irrelevant for small projects, can
grow to dominate the development time for larger projects. Figure 0-3 shows a com-
mon example of what appears to be a good idea at first but turns bad as the size of a
system grows. The myerror component defines a struct, MyError, that contains an
.enumeration of all possible error codes. Each new component that is added to the
system naturally includes this header file. Unfortunately, each new component may
have its own error codes that have not already been identified in the master list.
8 Introduction Chapter 0

II myerror.h
#ifndef INCLUDED_MYERROR
#define INCLUDED MYERROR
struct MyError {
enum Codes {
SUCCESS = 0,
WARNING,
ERROR,
IO_ERROR,
I I ...
READ_ERROR,
WRITE_ERROR,
I / .. .
/ / .. .
BAD_STRING,
BAD_FILENAME.
// .. .
// .. .
CANNOT_CONNECT_TO_WORK_PHONE,
CANNOT_CONNECT_TO_HOME_PHONE,
// .. .
// .. .
MARTIANS_HAVE_LANDEO,
// ...
};
};

#endif

Figure 0-3: An Insidious Source of Compile-Time Coupling

As the number of components gets larger, our desire to add to this list will wane. We
will be tempted to reuse existing error codes that are, perhaps, only roughly appropri-
ate just to avoid changing myerror. h. Eventually, we will abandon any thought of add-
ing a new error code, and simply return ERROR or WARNING rather than change
myerror. h. By the time we reach this point, the design is unmaintainable and practi-
cally useless.
section 0.2.3 Excessive Compile-Time Dependencies 9

There are many other causes of unwanted compile-time dependencies. A large C++
program tends to have many more header files than an equivalent C program. The
unnecessary inclusion of one header file by another is a common source of excessive
coupling in c++. In Figure 0~4, for example, it is not necessary to include the defini-
tion of objects in the simulator header file just because a client of class Si mu1 at 0 r
may find these definitions useful. Doing so forces the client to depend at compile-
time on all such components whether or not they are actually used. Excessive include
directives not only increase the cost of compiling the client, but increase the likeli-
hood that the client will need to be recompiled as a result of a low-level change to the
system.

By ignoring compile-time dependencies, it is possible to cause each translation unit in

the system to include nearly every header file in the system, reducing compilation
speed to a crawl. One of the first truly large c++ projects (literally thousands of staff
years) was a CAD framework product developed at Mentor Graphics. The developers
initially had no idea how much compile-time dependencies would impede their
efforts. Even using our large network of workstations, recompiling the entire system
was taking on the order of a week!

The problem was due to organizational details illustrated in part by the simulator
component shown in Figure 0-4. Cosmetic techniques were developed to mitigate this
problem, but the real solution came when the unnecessary compile-time dependencies
were eliminated.
10 Introduction Chapter 0

II simulator.h
#ifndef INCLUDED_SIMULATOR
#define INCLUDED_SIMULATOR
#include "cadtool.h" II required by "IsA" relationship
#include "myerror.h" II bad idea (see'Section 6.9)
If inc 1ude" c i r cui t reg i s try. h I! II unnecessary compile-time dependency
#include "inputtable.h" II unnecessary compile-time dependency
#include "circuit.hl! II required by "HasA" relationship
#include "rectangle.h" II unnecessary compile-time dependency
/ I ...
#include <iostream.h> II unnecessary compile-time dependency

class Simulator: public CadTool { II mandatory compile-time dependency

CircuitRegistry *d_circuitRegistry_p;
InputTable& d_inputTable;
Circuit d_currentCircuit; II mandatory compile-time dependency
I / ...
private:
Simulator(const Simulator &);
Simulator& operator=(const Simulator&);
public:
Simulator();
-Simulator();
I I ...
MyError::Code readlnput(istream& in. canst char *name);
MyError::Code writeOutput(ostream& out. const char *name):
MyError::Code addCircuit(const Circuit& circuit);
MyError::Code simulate(const char *autputName,
const char *inputName,
const char *circuitName);
Rectangle window(const char *circuitName) canst;
I / ...
};

#endif

Figure 0-4: Unnecessary Compile-Time Dependencies

As with link-time dependencies, there are several specific techniques available for
eliminating compile-time dependencies.

0.2.4 The Global Name Space

If you have ever worked on a mUlti-person C++ project, then you know that software
integration is a common forum for unwanted surprises. In particular, the proliferation
of global identifiers can become problematic. One obvious danger is that these names
can collide. The consequence is that the individually developed parts of the system
Section 0.2.4 The Global Name Space 11

cannot be integrated without modification. For larger projects with hundreds of

header files, it can be difficult even to find the declarations of a global name.

For example, I have used object libraries that have consisted of literally thousands of
header files. I recall trying to find the definition of a type Tar get I d at file scope that
looked like a class (but wasn't):

Targetld id;

I remember trying to "grep,,3 through all of the thousands of header files looking for
the definition, only to receive a message to the effect that there were too many files. I
wound up having to nest the grep command in a shell script that split up the header
files based on the first letter in order to pare down the problem into 26 problems of
manageable size. I eventually discovered that the "class" I was looking for was not a
cl ass at all. Nor was it a struct or a uni on! As illustrated in Figure 0.5, the type
Ta rget I d, it turned out, was actually a typedef declaration at file scope for an i nt!

II upd_system.h
#ifndef INCLUDED_UPD_SYSTEM
#define INCLUDED_UPD_SYSTEM

typedef int Targetld; II bad idea!

class upd_System {
I I ...
public:
II
};

#endif

Figure 0-5: Unnecessary Global Name Space Pollution

The typedef had introduced a new type name into the global name space. There was
no indication that type was an i nt, nor was there any hint of where I might find its
definition.

3 "grep" is a Unix search utility program'.

12 Introduction Chapter 0

II upd_system.h
#ifndef INCLUDED_UPD_SYSTEM
#define INCLUDED_UPD_SYSTEM

class upd_System {
I I ...
public:
typedef int Targetld; II much better!
II
};

#endif

Figure 0-6: Typedefs in Class Scope Are Easy to Find

Had the typedef declaration been nested within a class (as suggested in Figure 0-6),
the reference would have been qualified with that class name (or the declaration
would have been inherited), making it straightforward to track down:

upd_System: :Targetld id;

Following simple practices like the one suggested above can minimize the likelihood
of collisions and at the same time make logical entities easier to find in large systems.

0.2.5 Logical vs. Physical Design

Most books on C++ address only logical design. Logical design is that which pertains
to language constructs such as classes, operators, functions, and so on. For example,
whether a particular class should or should not have a copy constructor is a logical
design issue. Deciding whether a particular operator (e.g., 0 per a to r==) should be a
class member or a free (i.e., nonmember) function is also a logical issue. Even select-
ing the types of the internal data members of a class would fall under the umbrella of
logical de~ign.

c++ supports an overwhelmingly rich set of logical design alternatives. For example,
inheritance is an essential ingredient of the object-oriented paradigm. Another, called
layering, involves composing types from more primitive objects, often embedded
directly in the class definition. Unfortunately there are many who would try to use
inheritance where layering is indicated: A Telephone is not a kind of Recei ver, Di al,
or Cor d; rather, it is composed of (or "layered on") those primitive parts.
Section 0.2.5 Logical vs. Physical Design 13

Misdiagnosing a situation in this way can lead to inefficiencies in both time and space,
and can obscure the semantics of the architecture to a point where the entire system
becomes difficult to maintain. Knowing when (and when not) to use a particular lan-
guage construct is part of what makes the experienced C++ developer so valuable.

Logical design does not address issues such as where to place a class definition. From
a purely logical perspective, all definitions at file scope exist at the same level in a sin-
gle space without boundaries. Where a class is defined relative to its member defini-
tions and supporting free operators is not relevant to logical design. All that is
important is that these logical entities somehow come together to form a working pro-
gram, and that, because the entire program is thought of as a single unit, there is no
notion of individual physical dependencies. The program as a whole depends on itself.

There are several good books on logical design (see the bibliography). Unfortunately,
there are also many problems, which arise only as programs get larger, that these
books do not address. This is because much of the material relevant to successful
large-system design falls under a different category, referred to in this book as
physical design.

Physical design addresses the issues surrounding the physical entities of a system (e.g.,
files, directories, and libraries) as well as organizational issues such as compile-time or
link-time dependencies between physical entities. For example, making a member
ri ng() of class Telephone an i nl i ne function forces any client of Tel ephone to
have seen not only the declaration of r i n9 ( ) but also its definition in order to com-
pile. The logical behavior of r i n9 () is the same whether or not r i n9 () is declared
i n 1 i ne. What is affected is the degree and character of the physical coupling between
Tel e p h0 ne and its clients, and therefore the cost of maintaining any program using
Telephone.

Good physical design, however, involves more than passively deciding how to partition
the existing logical entities of a system. Physical design implications will often. dictate
the outcome of logical design decisions. For example, relationships between classes
in the logical domain, such as IsA, HasA, and Uses, collapse into a single relation-
ship, DependsOn, between components in the physical domain. Furthermore, the
dependencies of a sound physical design will form a graph that has no cycles. There-
fore we avoid logical design choices that would imply cyclic physical dependencies
among components.
14 Introduction Chapter 0

Simultaneously satisfying the constraints of both logical and physical design may, at
times, prove challenging. In fact, some logical designs may have to be reworked or
even replaced in order to meet the physical design quality criteria. In my experience,
however, there have always been solutions that adequately address both domains,
although it may (at first) take some time to discover them.

For small projects that fit easily into a single directory, physical design may warrant
little concern. However, for larger projects the importance of a sound physical design
grows rapidly. For very large projects, physical design will be a critical factor in deter-
mining the success of the project.

0.3 Reuse

Object-oriented design touts reuse as an incentive, yet like many other benefits of the
paradigm, it is not without cost. Reuse implies coupling, and coupling in itself is
undesirable. If several programmers are attempting to use the same standard component
without demanding functional changes, the reuse is probably reasonable and justified.

Consider, however, the scenario where there are several clients working on different
programs, and each is attempting to "reuse" a common component to achieve some-
what different purposes. If those otherwise independent clients are actively seeking
enhancement support, they could find themselves at odds with one another as a result
of the reuse: an enhancement for one client could disrupt the others. Worse, we could
wind up with an overweight class (like the st r i n 9 class of Figure 0-2) that serves the
needs of no one.

Reuse is often the right answer. But in order for a component or subsystem to be
reused successfully, it must not be tied to a large block of unnecessary code. That is, it
must be possible to reuse the part of the system that is needed without having to link
in the rest of the system.

Not all code can be reusable. Attempting to implement excessive functionality or

robust error checking for implementation objects can add unnecessarily to the devel-
opment and maintenance cost as well as to the size of the executable.

Large projects stand to benefit from their implementors' knowing both when to reuse
code and when to make code reusable.
section 0.4 Quality 15

0.4 Quality

Quality has many dimensions. Reliability addresses the traditional definition of quality
(Le., "Is it buggy?"). A product that is easy to use and does the right thing most of the
time is often considered adequate. For some applications, however-in areas such as
aerospace, medical, and financial, for example--errors can be extremely costly. In
general, software cannot be made reliable through testing alone; by the time you are
able to test it, the software's intrinsic quality has already been established. Not all
software can be tested effectively. For software to be tested effectively, it must be
designed from the start with that goal in mind.

Design for testability, although rarely the first concern of smaller projects, is of para-
mount importance when successfully architecting large and very large C++ systems.
Testability, like quality itself, cannot be an afterthought: it must be considered from
the start-before the first line of code is ever written.

There are many other aspects to quality besides reliability. Functionality, for example,
addresses whether a product does what the customer expects. Sometimes a product
will fail to gain acceptance because it does not have enough of the features that
customers have come to expect. Worse, a product can miss its mark altogether: if a
customer expects to buy a screwdriver, the best hammer in the world will fail a function-
ality test. Having a clear functional specification that meets marketing requirements
before development is underway is an important first step toward ensuring appropriate
functionality. In this book, however, we consider techniques that address how to
design and build large systems, and not what large systems to design.

Usability is yet another measure of .quality. Some software products can be very
powerful in the right hands. However, it is not enough that the developer be able to
use the product effectively. If the product is too complex, difficult, awkward, or pain-
ful for the typical intended customer to pick up and use, it will not be used. Often
when we say user, we think of the end user of the system. In a large, hierarchically
designed system, however, the clients of your component are probably just other com-
ponents. Early feedback from customers (including other developers) is essential for
ensuring usability.

Maintainability measures the relative cost to support a working system. Support

includes such things as tracking down bugs, porting to new platforms, and extending
the features of the product to meet the anticipated (or even unanticipated) future needs
16 Introduction Chapter 0

of customers. A poorly designed system written in C++ (or any other language, for
that matter) can be expensive to maintain and even more expensive to extend. Large,
maintainable designs don't just happen; they are engineered by following a discipline
that ensures maintainability.

Peiformance addresses how fast and small the product is. Although object-oriented
design is known to have valuable advantages in the areas of extensibility and reuse,
there are aspects of the paradigm that, if applied naively, can cause programs to run
more slowly and require more memory than is necessary. If our code runs too slowly,
or if it requires much more memory than a competitor's product, we cannot sell it. For
example, modeling every character in a text editor as an object, although perhaps
theoretically appealing, could be an inappropriate design decision if we are interested
in optimal space/time performance. 4 Attempting to replace a heavily used funda-
mental type (such as i n t) with a user-defined version (such as a Big I nt class) will
inevitably degrade performance. If we fail to address our performance goals in the
beginning, we may adopt architectures or coding practices that will preclude our ever
achieving these goals, short of rewriting the entire system. Knowing where to accept
some inelegance and knowing how to contain the effects of performance trade-offs
distinguishes software engineers from mere programmers.

Each of these dimensions of quality is important to the overall success of a product.

However, achieving each of them has one thing in common: we must consid~r each
aspect of quality from the very start of a project. There is simply no way to add the
quality once the design is complete.

0.4.1 Quality Assurance

Quality assurance (QA) is typically an organization within a company responsible for

"assuring" that a certain measure of quality has been attained. A significant obstacle
to achieving high-quality software is that QA often does not get involved until late in
the development process, after the damage is already done. QA often does not influ-
ence the design of a software product. QA is rarely involved in low-level engineering
design decisions. Typically, the testing that QA performs is at the end-user level, and
it relies on the developers themselves for any low-level regression testing.

4 See the Flyweight pattern in gamma, Chapter 4, pp. 195-206 for a clever solution to this particu-
lar kind of performance problem.
Section 0.4.2 Quality Ensurance 17

In this all-too-common process model, it is engineering's job to produce raw software

that it then "throws over the wall" to QA. The software is often poorly documented,
hard to understand, difficult to test, and unreliable. QA i~ now, somehow, expected to
instill quality into the software. But how? Over and over, this model for assuring qual-
ity has demonstrated its ineffectiveness at achieving high-quality software in large
projects. We now suggest a different model.

0.4.2 Quality Ensurance

QA must become an integral part of development. In this process model, developers

have the responsibility for ensuring quality. That is, the quality must already be there
in order for test engineers to find it.

In this process model, the distinction of QA and development is blurred; the technical
qualifications for either position are essentially the same. One day, an engineer could
write an interface and have another engineer review it for consistency, clarity, and
usability. The next day the roles could be reversed. To be truly effective, the culture
must be one of teamwork-each member helping the other to ensure high-quality
software as it is being developed.

Providing a complete process model is a huge task and well beyond the scope of this
book. However if high-quality software is to be achieved, system architects and soft-
ware developers must take the lead by designing in the quality all along the way.

0.5 Software Development Tools

Large projects can benefit from many kinds of tools, including browsers, incremental
linkers, and code generators. Even simple tools can be very useful. A detailed descrip-
tion of a simple dependency analyzer that I have found invaluable in my own work is
provided in Appendix C.

Some tools can help to mitigate the symptoms of a poor design. Class browsers can
help to analyze convoluted'designs and find definitions for logical entities that would
otherwise be hidden-buried within a large project. Sophisticated programming
environments with incremental linkers and program databases can help to push the
envelope of what can be accomplished even with a poor physical design. But none of
these tools address the underlying problem: a lack of inherent design quality.
18 Introduction Chapter 0

Unfortunately there is no single quick and easy way to achieve quality. Tools alone
cannot solve fundamental problems resulting from a poor physical design. Although
tools can postpone the onset of some of these symptoms, no tool will design in the'
quality for you, nor will it ensure that your design complies with its specification.
Ultimately, it is experience, intelligence, and discipline that yield a quality product.

0.6 Summary

c++ is a whole lot more than just an extension of C. Cyclic link-time dependencies
among translation units can undermine understanding, testing, and reuse. Unnecessary
•
or excessive compile-time dependencies can increase compilation cost and destroy
maintainability. A disorganized, undisciplined, or naive approach to C++ development
will virtually guarantee that these problems occur as projects become larger.

Most C++ design books address only logical issues (such as classes, functions, and
inheritance) and ignore physical issues (such as files, directories, and dependencies).
In larger systems, however, physical design quality will dictate the correct outcome of
many logical design decisions ..

Reuse is not without cost. Reuse implies coupling, and coupling can be undesirable.
Unwarranted reuse is to be avoided.

Quality has many dimensions: reliability, functionality, usability, maintainability, and per-
formance. Each of these dimensions contributes to the success or failure of large projects.

Achieving quality is an engineering responsibility: it must be actively sought from the

start. Quality is not something that can be added after a project is largely complete. For
a QA organization to be effective, it must be an integral part of the entire design process.

Finally, good tools are an important part of the development process. But tools cannot
make up for a lack of inherent design quality in large C++ systems. This book is about
how to design in that quality.
 PART I:

This book covers quite a bit of material relating to object-oriented design and C++
programming. Not all readers will have the same background. In Part I of this text, we
address the fundamentals in an effort to reach a common starting point from which to
launch further discussions.

Chapter 1 is a review of several key properties of the C++ language, basic object-
oriented design principles and notation, and standard coding and documentation
conventions used throughout this text. The purpose of this chapter is to help level the
field. It is expected that much of this material will be familiar to many readers. Nothing
presented here is new. Expert C++ programmers may choose to skim this chapter or
simply refer to it as needed.

Chapter 2 describes a modest collection of commonsense design practices that most

experienced software developers have already discovered. Adherence to the fundamen-
tal rules presented here is an integral part of successful software design. These rules also
serve to frame the more advanced and subtle principles and guidelines presented
throughout the book.
 Preliminaries

This chapter reviews some important aspects of the C++ programming language and
object-oriented analysis that are fundamental to large-system design. Nothing revolu-
tionary is presented; some material, however, may be unfamiliar. We start by examin-
ing multi-file programs, declaration versus definition, and internal versus external
linkage in the contexts of both header (. h) and implementation (. c) files. Next we
explore the use of typedef declarations and ass~rt statements. After considering a few
matters of style regarding naming conventions and class member layout, we explore
one of the most common object-oriented design patterns: iterator. We conclude with
a thorough discussion of the logical design notation used throughout this book, a
brief discussion of inheritance versus layering, -and, finally, a recommendation for
minimality in our interfaces.

1.1 Multi..File C++ Programs

For all but the tiniest programs, it is neither wise nor practical to place an entire program
in a single file. For one thing, each- time you made a change to any part of the program,
you would be forced to recompile the program in its entirety. You also would not be
able to reuse any part of your program in another program without copying the source
code to another file. Such duplication can quickly become a maintenance headache.

PlaCing the source code for cohesive parts of a program in separate files enables the
program to be compiled more efficiently, while enabling its parts to be reused in other
programs.
22 Preliminaries Chapter 1

In this section, we review some basic properties of the structure of the C++ language with
regard to programs that are created from several source files. These concepts will be
used frequently throughout this book.

1.1.1 Declaration versus Definition

A declaration is a definition unless: 1

• it declares a function without specifying its body,

• it contains an ext ern specifier and no initializer or function body,
• it is the declaration of a static class data member within a class definition,
• it is a class name declaration, or
• it is a typedef declaration.

A definition is a declaration unless:

• it defines a static class data member or

• it defines a non-inline member function.

DEFINITION: A declaration introduces a name into a program; a

definition provides a unique description of an entity (e.g., type,
instance, function) within a program.

A declaration introduces a name into a scope. A declaration differs from a definition

in that it is legal in C++ to repeat a declaration within a given scope. By contrast, there
must be exactly one definition of each entity (e.g., class, object, enumerator, or func-
tion) used in the program. For example,

int f(int,int);
int f(int,int);
class IntSetIter;
class IntSetIter;
typedef int Int;
typedefint Int;
friend IntSetlter;
friend IntSetlter;
extern int globalVariable; II bad idea (global variable declaration)
extern int global Variable; II (see Section 2.3.1)

1 ellis, Section 3.1. o. 14.

Section 1.1.2 Internal versus External Linkage 23

are all declarations, and can be repeated any number of times within a single scope.
On the other hand, the following declarations at file scope are also definitions, and
therefore cannot be seen more than once in a given scope without triggering a compile-
time error:

int x; II bad idea (global variable)

char *p; II bad idea (global variable)
extern int globalVariable = 1; II bad idea (global variable)
static int s instanceCount;
static int f(int int) {/*
t */}
inline int hCint, int) {/* */}
enum Color { RED, GREEN. BLUE };
enum DummyType {};
enum { SIZE = 100 };
enum {} silly;
const double DEFAULT TOLERANCE = 1.0e-6;
class Stack { 1* ... *1 };
struct Util { 1* ... *1 };
union Rep { 1* ... *1 };
template(class T> void sort(const T** array, int size) { 1* ... *1 }

We should note that function and static data member declarations are exceptions that,
although not definitions, may not be repeated within the definition of a class:

class NoGood {
static int 1 • t II declaration
static int i ; II illegal in C++
public:
int f(); II declaration
int f(); II illegal in C++
};

1.1.2 Internal versus External Linkage

When a . c file is compiled, the header files are first included (recursively) by the C
preprocessor (cpp) to form a single source file containing all the necessary informa-
tion. This intermediate file (called a translation unit) is then compiled to produce a . 0
file (object file) with the same root name. Linkage connects the symbols produced
within the various translation units to form an executable program. There are two dis-
tinct kinds of linkage: internal and external. The kind of linkage used will directly
influence how we incorporate a given logical construct in our physical design.
24 Preliminaries Chapter 1

DEFINITION: A name has internal linkage if it is local to its transla-

tion unit and cannot collide with an identical name defined in
another translation unit at link time.

Intemallinkage means that access to the definition is limited to the current translation
unit. That is, a definition with internal linkage is not "visible" to any other translation
unit and therefore cannot be used to resolve undefined symbols during the linking
process. For example,

static int x;

is defined at file scope, but the keyword s tat i c forces the linkage to be internal.
Another example of internal linkage is an enumeration:

enum Boolean { NO, YES };

Enumerations are definitions (not just declarations), but never themselves introduce
symbols into the . 0 file. In order for definitions with internal linkage to affect other
parts of a program, they must be placed in the header file, not the . c file.

An important example of a definition with internal linkage is that of a class. The

description of class Poi nt (shown in Figure 1-1) is a definition, not a declaration;
hence, it cannot be repeated in a translation unit in the same scope. For classes to be
used outside of a single translation unit, they must be defined in a header file. An
inline function definition (such as the one shown for ope r a to r== at the bottom of Fig-
ure 1-1) is another example of a definition with internal linkage.

class Point {
int d_x;
i nt d-y;

public:
Point Ci nt x, int y) .. d_x (x) , d-y(y) { } II internal linkage
int xC) canst { return d- x', } II internal linkage
i nt y ( ) const { return d-y; } II internal linkage
II . . .
}; II internal linkage
inline int operator==(const Paint& left, canst Point& right)
{
return left.xC) == right.xC) && left.y() == right.y();
} II internal linkage
section 1.1.2 Internal versus External Linkage 25

DEFINITION: A name has external linkage if, in a multi-file pro-

gram, that name can interact with other translation units at link
time.

External linkage means that the definition is not limited to a single translation unit.
Definitions with external linkage produce external symbols in the . 0 file that are
accessible by all other translation units for resolving their undefined symbols. Such
external symbols .must be unique throughout the program or the program will not link.

Non-inline member functions (including static members) have external linkage, as do

non-inline, non-static free (i.e., nonmember) functions. Examples of functions with
external linkage are shown in Figure 1-2.

II non-inline member function:

Point& Point: :operator+=(canst Point& right)
{
d_x += right.d_x;
d-y += right.d_y;
return *this;
} II external linkage

II non-inline free function:

Point operator+(const Point& left. canst Point& right)
{
return Point(left.x() + right.xC), left.yC) + right.yC));
} II external linkage

Figure 1-2: Some Function Definitions with External Linkage

Note that we will consistently refer to a nonmember function as a free function and
never as afriendfunction. A free function need not be a friend of any class; whether
or not it is should be an implementation detail (see Section 3.6).

Where possible, the C++ compiler substitutes the body of an inline function directly
in place of the function call and introduces no symbols into the . 0 file. Sometimes the
compiler will elect (for various reasons, such as·recursion or dynamic binding) to lay
down a static copy of an inline function. This static copy introduces only a local sym-
bol into the current . 0 file, which cannot interact with external symbols.
26 Preliminaries Chapter 1

Because a declaration is solely for the benefit of the current translation unit,
declarations themselves introduce nothing at all into a . 0 file. Consider the following
declarations:

1* 1 *1 int fC); II bad idea (see Section 2.3.2)

1* 2 *1 extern int i ; II bad idea (see Section 2.3.1)
struct S {
1* 3 *1 int g(); II fine
};

None of these declarations themselves affects the contents of the resulting .0 file.
Instead, each of these declarations merely names an external symbol, enabling the
current translation unit to gain access to the corresponding global definition if needed.
It is actually the 'use of the symbol name (e.g., calling a function) and not the declara-
tion itself that causes an undefined symbol to be introduced into the . 0 file. It is precisely
this fact that allows early prototyping: as long as the missing functionality is not
needed, partially implemented objects can be used in running programs.

In the previous example, each of the three declarations enabled access to an externally
defined function or object. We might be sloppy and say that these "declarations" have
external linkage. But there are other kinds of declarations that do not serve to enable
access to external definitions. We will often refer to these kinds of declarations as
having "internal" linkage. For example,

typedef int Int; II internal linkage

is a typedef declaration. It does not introduce any symbols into the . 0 file, nor does it
enable access to a global object with external linkage: its linkage is internal. An
important kind of declaration that happens to have internal linkage is that of a class.

class Point; II internal linkage

struct Point; II internal linkage
union Point; II internal linkage

All of the above have the identical effect of introducing the name Poi n t as some kind
of user-defined type; the particular declaration type (e.g., c1 ass) need not match the
actual definition type (e.g., un ion):

class Rep;
I / ...
union Rep {
// ...
1 •
Section 1.1.3
Header (. h) Files 27

The definitions to which these declarations potentially refer also have internal link-
age; this property distinguishes class declarations from the external declarations in
previous examples. Both class declarations and class definitions contribute nothing to
the . 0 file and are solely for the benefit of the current translation unit.

On the other hand, static class data members (declared within the class definition)
have external linkage:

class Point {
static int s numPoints; II declaration of external object
I I ...
};

The static class data member s_numPoi nts (shown above) is only a declaration, but
, its definition in the . c file has "external" linkage:

II point.c
int Point::s_numPoints; II definition of external object
II (initialized to 0 by default)

Note that, according to the language specification, every static class data member
must be defined exactly once somewhere in the final program. 2

Finally, the c++ language treats enumerations and classes differently:

enum Point; II error

It is not possible in c++ to declare an enumeration without defining it. As we will see,
class declarations are quite often used in place of preprocessor inc 1 ude directives to
declare a class without defining it.

1.1.3 Header (. h) Files

In C++ it is almost always a programming error to place a definition with external

linkage in a . h file. If you do, and you include that header in more than one translation
unit, linking them together will fail with a message such as

MULTIPLY DEFINED SYMBOL.

2 e1Iis , Section 9.4, p.179; Section 18.3, p. 405.

28 Preliminaries Chapter 1

It is legal in c++ to place definitions with intemallinkage, such as static functions or

static data, at file scope within a header file, but it is undesirable. Not only do these
file-scope definitions pollute the global name space but, in the case of static data and
functions, they consume data space in every translation unit that includes the header.
Even data declared con stat file scope can cause this same problem, especially if the
address of the constant is ever taken. Compare a file-scope constant (with internal
linkage) with a static constant class member (which has extemallinkage): there will
be only a single copy of the class-scoped constant in the entire program. Some exam-
ples of what does and doesn't belong in a header file are provided in Figure 1.3.

II radio.h
#ifndef INCLUDED_RADIO
#define INCLUDED RADIO

int z; II illegal: external data definition

extern int LENGTH = 10; II illegal: external data definition
const int WIDTH = 5; II avoid: constant data definition
static int y; II avoid: static data definition
static void func() {/* ..• */} II avoid: static function definition

class Radio {
static int s_count; II fine: static member declaration
static canst double S- PI·, II fine: static canst member dec.
int d_size; 1/ fine: member data definition
I / ...
public:
int size() canst; II fine: member function declaration
I I ...
}; II fine: class definition

inline int Radio::size() canst

{
return d_size;
} II fine: inline function definition

int Radio::s_count; II illegal: static member definition

double Radio::"S_PI = 3.14159265358; II illegal: static const member def.

int Radio::size() canst { I* ... */} II illegal: member function definition

#endif

Figure 1-3: What Does and Does Not Belong in a Header File

The redundancy of duplicated nonmember data definitions affects not only program size
but also runtime performance by defeating the caching mechanism of the host computer.
Section 1.1.4 Implementation ( . c) Files 29

Occasionally, however, there are valid reasons for placing a static instance of a user~
defined object in a header file at file scope. In particular, the constructor of such an
object can be used to ensure that a particular global facility (such as i ostream) has
been initialized before it is used. 3 Although this solution may be elegant for small and
medium-sized systems, it is problematic for very large systems. We will return to this
issue in Section 7.8.1.3.

1.1.4 Implementation (. c) Files

We will sometimes elect to define functions and data for use in our own implementation
that we do not want exposed outside of our translation unit. Definitions with internal
but not external linkage can appear at file scope in a . c file without affecting the glo-
bal (symbol) name space. The definitions to be avoided at file scope in . c files are
data and functions that have not been declared static. For example,

II filel.c

i nt i; II external linkage
int max(int a, int b) { return a > b ? a : b } II external linkage

The above definitions have external linkage and could potentially collide with other
similar names in the global name space. Because inline and static free functions have
internal linkage, these kinds of functions can be defined at file scope in a . c file and
not pollute the global name space. For example,

II file2.c

inline int min(int a, int b) { return a < b ? a : b } II internal

static int factCint n) { return n <= 1 ? 1 : n * fact(n - 1); } II internal

Enumeration definitions, nonmember objects declared s tat i c, and (by default) con s t
data definitions also have internal linkage. It is safe to define all of these entities at file
scope in the . c file. For example,

3 ellis, Section 3.4, pp. 21-22.

30 Preliminaries Chapter 1

II file3.c
#include <math.h>
class Link; 1/ internal

enum { START_SIZE = 1, GROW_FACTOR = 2 }; II internal

canst double PI - SO = M- PI * M-PI·

, II internal

static canst char *names[] = { "Ntran", "Ptran", "NPN", "PNP" }; I I internal

static Link *s_root_p; II internal

Link *const s_first_p = s_roat_p; II internal

Other constructs such as typedef declarations and preprocessor macros do not intro-
duce exported symbols into the . 0 file. They too may appear in . c files at file scope
without affecting the global name space. For example,

typedef int (PointerToFunctionOfVoidReturningInt *)();

ifdefinE CASE(X) case x: cout « "X" « endl; II Classic C preprocessor

#define CASE(X) case X: cout « #X « endl; II ANSI C preprocessor

Typedefs and macros have limited usefulness in C++, and they can be harmful if
abused. We will explore the perils of typedefs in Sections 1.2 and 2.3.3, and those of
macros in Section 2.3.4.

1.2 typedef Declarations

A typedef declaration creates an alias for an existing type, not a new type. A
typedef, therefore, gives only the illusion of type safety. Consequently, typedefs in
the interface can easily do more harm than good.

Consider class Person shown in Figure 1-4. We have decided to nest typedef
declarations within the Per son class to avoid affecting the global name space and to
make them easier to find. The set Wei 9 h t member function is defined to take a weight
argument in "Pounds," while the getHei ght method returns height in "Inches."
 typedef Declarations 31
Section 1.2

II person.h
#ifndef INCLUDED_PERSON
#define INCLUDED_PERSON

class Person {
I I ...
public:
typedef double Inches;
typedef double Pounds;
I I ...
void setWeight(Pounds weight);
Inches getHeight() const;
I I ...
};

lIendif

Figure 1-4: Typedefs Are Not Type-Safe

Unfortunately, a nested typedef offers no more type safety than one declared at file
scope:

void f (const Person& person)

{
Person::lnches height = person.height();
person.setWeight(height); II ok ??
};

The two type names Inc hesand Po Un ds are structurally equal and therefore com-
pletely interchangeable. These typedefs afford absolutely no compile-time type safety,
yet make it difficult to know the actual type.

Typedefs do, however, have their place when it comes to defining complex function
arguments. For example,

typedef int (Person: :*PCPMFDI)(double) canst;

declares PCPMFDI to be of type: pointer to a canst Person member function taking a

daub 1e argument and returning an ; nt. Typedefs are also useful in defining data
members that must maintain a constant size across different compilers and computer
hardware (see Section 10.1.3).
32 Preliminaries Chapter 1

1.3 Assert Statements

The standard C library provides a macro called ass e r t (see ass e r t . h) for guarantee-
ing that a given expression evaluates to a non-zero value; otherwise an error message
is printed and program execution is terminated. 4 Assertions are convenient to use and
are a powerful implementation-level documentation tool for developers. Assert state-
ments are like active comments-they not only make assumptions clear and precise,
but if these assumptions are violated, they actually do something about it.

The use of assert stat~ments can be an effective way to catch program logic errors at
runtime, and yet they are easily filtered out of production code. Once development is
complete, the runtime cost of these redundant tests for coding errors can be eliminated
simply by defining the preprocessor symbol NDEBUG during compilation. Be sure,
however, to remember that code placed in the assert itself will be omitted in the pro-
duction version. Consider the following partial definition of a St r i n 9 class:

class String {
enum { DEFAULT_SIZE = 8 };
char *d_array_p;
int d_size;
int d_length;

public:
String( };
I I ...
};

If (as with the code below) the expression argument to the ass e r t macro affects the
state of the software, then the production version will exhibit disparate behavior.

String: :StringC)
d_size (DEFAULT_SIZE)
, d_length(O)
{
II error
}

We can avoid this problem by making sure that the asserted code is completely inde-
pendent of the normal operation of the object:

4 plauger, Chapter 1, pp. 17-24.

Section 1.4 A Few Matters of Style 33

String: :String()
d_size CDEFAULT_SIZE)
, d_lengthCO)
{
d_array_p = new char[d_size]);
assertCd_array_p); II fine
}

A generalization of this technique that addresses fault tolerance is to t h rowan excep-

tion such as Cadi ngErrar. 5 This way it will be up to the software at higher levels to
cat chand address this problem. In the absence of a handler for programming errors,
the default behavior reduces to that of an assert. 6

1.4 A Few Matters of Style

When programmers get together to start a project, they often discuss what coding
standards to adopt. Few of these standards contribute to the quality of the product.
Often they are concerned with questions such as

Should we indent 2, 4, or 8 spaces?

Should we put a space between the right parenthesis of an i f statement and

the following left bracket like this

if (exp) {

Or should we not put a space like this

if (exp){

At the beginning of one big project, we spent weeks arguing about standards. We con-
cluded that although there is an advantage to standardization, the list of standards
should be as small as possible, and each should be driven by clear engineering princi-
ples. Both of the examples above fail these criteria.

Another thing we learned is that when it comes to enforcing standards, there are two
domains: the interface and the implementation. A good interface is much more impor-
tant than a good implementation. Interfaces have a direct impact on clients and they

5 murray, Section 9.2.1, pp. 208-210.

6 For more on the intended use of exceptions, see ellis, Section 15.1, p. 355.
34 Preliminaries Chapter 1

also have global implications. Implementations should affect only the authors and
maintainers of code.

There are clear reasons to impose strict standards on interfaces, particularly in large
projects. Interfaces are generally much more difficult and costly to repair than imple-
mentation. It is usually. not too difficult to throw out a poor implementation and
replace it with a better one, provided the interface is a good encapsulating one.

1.4.1 Identifier Names

The following coding conventions have been debated ad infinitum and have survived
the ordeal. Most of the recommendations proposed here focus on aspects that affect
interfaces, where their benefit will be most strongly felt. Then again, much of this is a
matter of personal taste. If there is one rule, it is to be consistent.

1.4.1.1 Type Names

c++ syntax is complex. Subtle clues about the nature of its constructs are always wel-
come. A fairly standard and widely accepted practice is to treat type names with spe-
cial consideration. In this text we consistently make the first character of a type name
an uppercase letter; non-type names begin with a lowercase letter.

For our purposes, types are those entities that are neither data nor functions:

• Classes
• Structures .
• Unions
• Typedefs
• Enumerations
• Templates
section 1.4.1.2 Multi-Word Identifier Names 35

Here are some declarations that illustrate this programming style:

class Point;
struct Date;
union Value;
enum Temperature { COLD, WARM, HOT, VERY HOT} temp;?
typedef Temp Temperature;
template class Stack<int>;
int Point::getX() const;
void Point::setX(int xCoord);

Lexicographically distinguishing type names from other names is an objectively veri-

fiable standard that improves readability for both clients and implementors alike. If
used consistently, this practice can make interfaces easier to understand and code eas-
ier to maintain.

1.4.1.2 Multi-Word Identifier Names

There are two kinds of people when it comes to naming identifiers-those who
advocate the use of the underscore character (~ _ ~) to delimit words, and those who
advocate capitalizing the second and subsequent words:

There are arguments for both sides. I was originally in the underscore camp but was
forced to make the change by consensus. Now I realize that it makes no difference: it
is just a matter of what you are used to. Perhaps the capitals are a bit better because
the names are shorter; they become easier to read once you are used to them. Using
capitals also leaves open the use of underscore for other purposes (see Sections 6.4.2
and 7.2.1). The important thing is that there be consistency throughout the product line.

It appears unprofessional and can be annoying for one set of classes to use one
naming convention while other classes in the same product use the other, especially
if outside paying customers will (or some day could) have direct access to the under-
lying C++ classes. Some programmers, however, may dismiss these inconsistencies as
simply a matter of style.

7 In
this text the names of enumerators and (static) constants are all uppercase and make use of
underscores to delimit words.
36 Preliminaries Chapter 1

In this book I have adopted the uppercaseStanda rd. Whatever you adopt, however, I
strongly recommend that you be_consi stent, particularly in the interface.

1.4.1.3 Data Member Names

Readability and maintainability are greatly served if people remember to add a consis-
tent prefix (such as d_) to the data members of their classes. Consider the following
Shoe class:

class Shoe
double d_temperature;
int d_size;
I I ...
public:
I I ...
void expand(double calories);
I I ...
void setSize(int size);
I I ...
};

Values held in local (automatic) variables within member functions are only tempo-
rary; they do not exist after the member function returns. On the other hand, class
member data defines the state of the object, which exists between member function
calls:

void Shoe::expand(double calories)

{
canst double FACTOR = 42.57; II Always initialized to same value
I I '" II (probably belongs at file scope).

double factor = calories * FACTOR; II short lived automatic variables

d_temperature += FACTOR I d_size; II use of "state" variables

}

The primary purpose of the d_ is to highlight class data members in a context-

independent, mechanical way. Because of the very different purposes for these two
types of data, lexicographically distinguishing class data member names from those
of local variables helps to make object implementations easier to understand.

It is common to see member functions that set an instance variable (e.g., d_s i ze) to
contain a single assignment expression:
Section 1.4.1.3 Data Member Names 37

inline
void Shoe::setSize(int size)
{

putting the d_ in front of data members also obviates dreaming up weird names (e.g.,
sz) for the manipulator function's argument:

void Shoe::setSize(int sz)

{
size = sz;
}

The choice of a d_ prefix is quite arbitrary_ We do not use only an underscore (_) as a
prefix because identifiers beginning with an underscore are reserved for use by C
compilers. 8 Some prefer to use a trailing underscore for this purpose:

void Shoe::setSize(int size)

{
size_ = size;
}

I find it useful to leave the suffix open for other purposes (such as _p to identify a
pointer data member).9 You may also want to use a different prefix (such as s_ to
identify static class data). Whether in a class or at file scope, non-canst static data
potentially contains instance-independent state information. As discussed in Section
6.3.5, static class data members may be moved to file scope in a . c file to help avoid
compile-time coupling. Because of the very similar properties and interchangeability
of these two types of data, it makes sense to identify state variables in the . c file with
an s_ as well. Consistently following this naming convention makes it easy to search
for all instance-independent state variables in a component.

It is worth noting that static class or file scope constant data is stateless. We can iden-
tify the nature and lifetime of this data simply by making its name all uppercase. For
constant data in class scope, a name such as S_DEFAULT_VALUE or simply
DEFAULT_VALUE could work equally well. In this book we prefer S_DEFAULT_VALUE
for class-scoped constant static data to remind us of the need to keep it private (see
Section 2.2).

8 ellis,
Section 2.4, p. 7.
9 See Section 6.4.2 for another use of an identifier suffix.
38 Preliminaries Chapter 1

By contrast, a non-static constant data member has a more limited lifetime and its
value need not always be the same in each incarnation of the object. Consequently, its
name would appear in lowercase and begin with a d_ prefix:

class Set { 1* ... *1 }

class Setlter {
Set *const d_set_p; II d_set_p is a canst pointer ta a Set.
const double D_PI; II bad idea (should be static)
I I ...
};

The d_ convention was adopted, without complaint, by our entire company.

1.4.2 Class Member Layout

When using an unfamiliar object, figuring out where to find things can be difficult.
Although member function ordering within a class is clearly a matter of style, from a
client's point of view it helps to be consistent. A fundamental way to classify member
functionality is by whether or not it potentially affects the state of the object.

An organization useful for both a developer and a client is illustrated in Figure 1-5.
This organization has the advantage of grouping by categories of functionality that are
present in nearly every C++ class. This organization is also independent of the partic-
ular abstraction being implemented.

class Car {
I I ...
public:
II CREATORS
Car(int cost = 0);
Car(const Car& car);
""'CarC);

II MANIPULATORS
Car& operator=(const Car& car);
void addFuel(double numberOfGallons);
void drive(double deltaGasPedal);
void turn(double anglelnDegrees);
I I ...

II ACCESSORS
double getFuel() const;
double getRPMs() const;
double getSpeed() const;
I / ...
};

Figure 1-5: CreatorlManipulator/Accessor Member Or2anization

 Class Member Layout 39
section 1~4.2

CREATORS bring objects into and out of existence. Notice that operatar= is not a
creator, but rather (by convention) the first manipulator. MAN I PU LATORS are simply
non-canst member functions; ACCESSORS are canst member functions. This purely
objective grouping makes it easy to verify at a glance that all of the accessors and
none of the manipulators are declared as con s t members of the class. But the princi-
pal benefit is to provide a common starting point for dissecting the fundamental func-
tionality of an unfamiliar class. For larger classes, it can be helpful to sort members
within each section alphabetically. For very large classes such as wrappers (discussed
in Sections 5.10 and 6.4.3), other organizations may be more appropriate.

Sometimes people will try to group member functions as get/set pairs as illustrated in
Figure 1-6. For some users, .this style is a result of the misguided belief that an object
is little more than a public data structure that has data members, each of which must
have both a "get" (accessor) function and a "set" (manipulator) function. This style
itself could, for some, impede the creation of truly encapsulated interfaces in which the
data members are not necessarily transparently reflected in the behavior of the object.

class Car {
double d_fuel;
double d_speed;
double d_rpms;

public:
CarCint cost = 0);
Car(const Car& car);
Car& operator=(const Car& car);
..... Ca r ( ) ;

double getFuel () canst;

void setFuel(double numberOfGallons);

double getRPMs() canst;

void setRPMs(double rpms);

double getSpeed() const;

void setSpeed(double speedlnMPH);

// ...
};

Figure 1..6: Get/Set Member Organization

Finally, there is the question of where to place the data members. Properly encapsu-
lated classes do not have public data. From a logical point of view, data members are
40 Preliminaries Chapter 1

merely implementation details of the class6 Consequently, many people prefer to place
the implementation details of a class, including the data members, at the end of the
class definition, as illustrated in Figure 1-76

class Car {
public:
Car(int cost = 0);
Car(const Car& car);

// ...
private:
do ub1e d_ f ue1 ;
double d_speed;
double d_rpms;
};

Figure 1-7: Trailing Data Member Organization

Although this organization may be more readable to naive clients, the attempt to hide
the implementation details at the end of the class definition belies the fact that they are
not hidden. The presence of implementation details in the header file imposes a
degree of compile-time coupling that does not evaporate simply by relocating these
details within the class definition.

Since this book addresses physical and organizational design issues, we consistently
place implementation details in the header file ahead of the public interface (partly to
emphasize their presence). In Chapter 6, we discuss how such implementation-level
clutter can be removed from a header file entirely, and thus truly hidden from the client.

1.5 Iterators

Perhaps the most common pattern in object-oriented design is that of an iterator. 10, 11
An iterator is an object that is intimately coupled to and supplied with a primary
object of some kind; its purpose is to allow clients to sequence through the parts,
attributes, or subobjects of the primary object.

Often objects will represent a collection of other objects. Such objects are commonly
referred to as containers. Sets, lists, stacks, heaps, queues, hash tables, and so on are

10 gamma, [terator, Chapter 5, pp. 257-271.

II strODstrup, Sections 5.3.2, p. ) 60; 7.8, p. 243; and 8.3.4, p. 267.
Section 1.5 Iterators 41

typical container objects. Note that where relevant, we often identify the source file
for a body of code with a leading comment. For example,

// stack.h // stack.c
#ifndef INCLUDED_STACK 1fi nc1 ude" s t a c k . h "
// ... I / ...

Consider, for example, the simple class implementing a set of integers shown in Fig-
ure 1-8. As we can see from its header file, I nt Set is implemented using I n t Set Lin k
objects, but that fact is an encapsulated implementation detail of the class. In this min-
imal implementation, we have elected to prevent users from constructing a copy of an
I nt Set or assignirig to one by making these otherwise automatically generated func-
tions private. (The comment NOT IMPLEMENTED· indicates that the functionality
does not exist even privately.) Users of I ntSet are allowed only to create an empty
set, add integers to it, check for membership, and destroy it.

/1 intset.h
#ifndef INCLUDED_INTSET
#define INCLUDED INTSET

class IntSetLink;
class IntSetIter;
class ostream;

class IntSet {
// DATA
IntSetLink *d_root_p; // root of a linked list of integers

// FRIENDS
friend IntSetIter;

private:
// NOT IMPLEMENTED
IntSet(const IntSet&);
IntSet& operator=(const IntSet&J;

public:
// CREATORS
IntSetC);
// Create an empty set of integers.
'"" I ntSet ( ) ;
/1 Destroy this set.
42 Preliminaries Chapter 1

II MANIPULATORS
void add(int i);
II Add an integer to this set. If the given integer is
II already present, this operation has no effect.
II ACCESSORS
int isMember(int i) const:
II returns 1 if integer 1 is a member of the set,
II and 0 otherwise.
};

lfendif

Figure 1-8: A Simple Integer Set Class

A tiny test driver that exercises this limited functionality is shown in Figure 1-9. Note
that driver programs in this book are indicated by using the file name suffix . t . c.

II intset.t.c
#include "intset.h"
#include <iostream.h)

maine)
{
IntSet a;
a.add(l); a.add(2): a.add(3).; a.add(2); a.add(4); a.add(6);

for (int i = 0; i < 10; ++i) {

cout « ' ,« i « ' ,« (a.isMember(i) ? "yes" : "no");
}

cout « endl:
}

II Output:
II john@john: a.out
II O-no I-yes 2-yes 3-yes 4-yes 5-no 6-yes 7-no 8-no 9-no
II john@john:

Figure 1-9: Trivial Driver Exercising I ntSet Functionality

Suppose we would like to find out what members exist in the set in order to print
them. Theoretically, we could write the output function ourselves as shown in Figure
1-10, but the performance of that implementation would be somewhat lacking.
 Iterators 43
section 1.5

.#include <limits~h> II defines INT_MIN and INT_MAX

ostream& operator«(ostream& 0, canst IntSet& intSet)
{
a « "{ ";
for (int i = INT_MIN; i <= INT_MAX; ++i) {
if (intSet.isMember(i» {. .
a « i « ' ,
}
}
return a « '}';
}

Figure 1-10: Infeasible Implementation of IntSet Output Operator

An obvious solution is to make the 0 per a tor << function a friend of class I nt Set in
order to take advantage of its internal representation. We could do that, but what if a
client is not happy with the format supplied by this operator's implementation? What
happens if later we find we need to access the internal members, say, to compare two
I ntSet objects?

class IntSet {
I I ...
public:
I I ...
void reset();
II Reset to beginning of sequence of integers. The Current
II integer will be invalid only if the set is empty.
void advance();
II Advance to the next integer in the set. If the current
II integer was the last in the set, the current integer
II will be invalid after advance returns. Note that the
II behavior is undefined if the current integer is already
II not valid.
int current() canst;
II Return the current integer in the sequence. Note that the
II behavior is undefined if the current integer is not valid.
int isCurrentValid() canst;
II Return 1 if the current integer is valid, and a otherwise.
II Note that the current integer is valid if the set is not
II empty and we have not advanced beyond the last integer
II in the set.
}

Figure 1-11: Attempting to Add Iteration Capability to the Container Itself

44 Preliminaries Chapter 1

We could keep adding new members and friends, but each time we do, we put both
our clients and ourselves at risk by increasing the complexity of the class. Repeatedly
revisiting and extending the functionality of an object is a well-recognized way of
introducing bugs into software. Also, unless you plan to support multiple versions,
other clients that do not care about this new functionality will have it forced upon them.

Instead of dealing with these deficiencies one at a time, we can address most of them
at once by providing a general and efficient way to access the individual members of
the set. Suppose we decided to add this capability directly to the I ntSet class itself,
as depicted in Figure 1-11. It is now possible for a client to iterate through an instance
of class I nt Set and print out the contents of that object in any format that is desired.
Figure 1-12 illustrates some of the power of iteration. Regardless of how the imple-
mentation of the set may change, the client's code will not be affected.

ostream& aperator«(ostream& Ot canst IntSet& intSet)

{
0« "{ ";
for (intSet.resetC): intSet.isCurrentValidC); intSet.advance(» {
o « intSet.current() « t ':

}
return 0 « '}';
}

Figure 1-12: Another Implementation of the IntSet Output Operator

Unfortunately, there are still problems with the design shown in Figure 1-12. For a
given object, there can be at most one iteration going on at anyone time. Suppose we
are trying to implement a comparison function for our I ntSet and decide, for debug-
ging purposes, to print out the contents of the sets midway through the comparison
iteration. The print routine would have the unwanted side effect of corrupting the iter-
ation state for the comparison. The problem is that I nt Set allocates enough space to
hold state information for exactly one iteration. That space remains allocated whether
or not an iteration is active. If for some reason we want to have a pair of nested for
loops that iterate over the elements in the same set, we would have to duplicate the
entire set.

This problem could be addressed by having the client hold on to the internal state or
retain some other form of place holder. If the client allocates the state dynamically,
the client must remember to delete the state to avoid a memory leak.
section 1.5 Iterators 45

If the place holder is in the form of an integer index, there could be some additional
practical constraints on the underlying implementation of the set. For example, if the
set is implemented as a linked list (instead of an array), there is the potential for qua-
dratic-Le., O(N2)-behavior during iteration because each iteration of the for loop
would result in having to traverse the list.

The standard approach is to supply an iterator class along with each container class
(in the same header file). The iterator is declared a fri end of the container and
therefore has access to its internal organization. The iterator class is defined in the
same header file as the container class to avoid the problems associated with "long-
distance" friendship (discussed in Section 3.6). Iterators for concrete containers such
as IntSet are typically created on the program stack; thus their state is destroyed
automatically when the iterator goes out of scope. Iterator objects can be more space
efficient because the space for each iteration need exist only during the iteration
process itself. Also, any number of iterators can be independently active on a given
container at any time without interfering with one another.

As a practical matter, it is common for iterators to assume that the objects on which
they operate are not modified or destroyed during the course of iteration. It is also
common for the order in which objects are presented during iteration to be implemen-
tation dependent and subject to change without notice. Ideally, iterator developers
would explicitly state whether or not the order of iteration is defined. To be safe, cli-
ents of iterators should not assume an order unless one is specified.

Figure 1-13 illustrates the design of the standard iterator pattern used throughout this
book. This iterator object is intended for use with for loops. The syntax of this itera-
tor is quite terse. The use of the operators is by no means obvious, especially if you
have never seen them used this way before. One could easily argue that this style is an
abuse of operator overloading because readability is reduced. There is more to this
story, however.

class IntSetlter {
II DATA
IntSetLink *d_link_p; II root of linked list of integers

private:
II NOT IMPLEMENTED
IntSetlter(const IntSetIter&):
IntSetIter& operator=(const IntSetlter&):
46 Preliminaries Chapter 1

public:
// CREATORS
IntSetlter{const IntSet& IntSet);
// Create an iterator for the specified integer set.

----IntSetlter();
II Destroy this iterator (an unnecessary comment).

II MANIPULATORS
void operator++{);
/1 Advance the" state of the iteration to next integer in set.

/1 ACCESSORS
int operator()() canst;
/1 Return the value of the current integer.

operator canst void *() canst;

1/ Return non-zero value if iteration lS valid~ otherwise O.
};

Figure 1-13: A Standard Iterator for the I ntSet Container

Because of the frequency with which iterators can and do occur in large designs, the
most important consideration for developers must be consistency. If we avoid operator
overloading and use functions instead, it is important to use the same function names
every time; otherwise we will find ourselves unwittingly misnaming these functions
and forever having to revert to header files for the syntactic details. A representative few
of the many possible equivalent function names are shown in Figure 1-14.

it it.more( ) it.isMore() it.valid() it.notDone()

++it it.next( ) it~getNext() it.advance() it.getMore()
it ( ) it. i tern ( ) it.getltemC) it.element() it.value()

Figure 1-14: Which Names Should We Use?

Our experience has shown that adopting the operators indicated in the left column of
Figure 1-14 for each of these standard iteration methods produces a consistent, easy-
to-use, and soon familiar and easily recognized idiom for iteration over concrete
types. Whatever you decide to use, be sure to be consistent throughout your product
line. The final implementation of the I ntSet output operator is shown in Figure 1-15;
the terse iterator notation affords a succinct implementation.
 Logical Design Notation 47
Section 1.6

ostream& operator«(ostream& 0, const IntSet& intSet)

{
o « "{ ";
for "ClntSetlter it(intSet); it: ++it) {
o « i t() « t t

}
return 0 « '}t:
}

Figure 1-15: I ntSet Output Operator Using Succinct Iterator Implementation

The choice of pre-increment (++it) over the post-increment (it++) in Figure 1-15 is
deliberate; the post-increment version requires a second dummy argument and is not"
universally available. 12 Furthermore, the semantics of increment for an iterator more
closely pattern those for pre-increment when applied to the fundamental types (see
Section 9.1.1).

1.6 Logical Design Notation

Object-oriented design lends itself to a rich set of notations. 13 Most of these notations
denote relationships between the logical entities of a design.

DEFINITION:

NOTATION MEANING
C__
x _) X is a logical entity (e.g., class).

I x I x is a physical entity (e.g., tile).

IsA
B B is a kind of A.

U ses-In-The-Interface
BO---------------------A B uses A in B's interface.

Be Uses-In-The-Implementation A B uses A in B's implementation.

12 See ellis, Section 13.4.7, pp. 338-339.

13b
ooch, Chapter 5, pp. 171-228.
48 Preliminaries Chapter 1

Throughout this text, we consistently identify logical entities (e.g., classes, structures,
and unions) with an ellipse-like bubble:

class Car {
( Car) I I ...
};

as opposed to a rectangle for physical entities:

II car.c
car.c /finclude "car.hl!
II

For our purposes, three logical notations will suffice:

class Car: publiC Vehicle {

( Car )J-.--_____I_sA_ _ _~......( Vehicle) }; / / ...

class Car {
I I ...
h - - Uses-In-The-Interface ( ) public:
( Car f -------f Ga~ void addFuel(Gas *);
/ I ...
};

class Car {
( Car )_~_U_s_e_S-_In_-_T_he_-_Im
_____ ----f( Engine)
pl_e_m_e_n_ta_ti_o_n Engine d_motor;
I I ...
};

If there is ever a need for additional logical notation, a labeled arrow that explicitly
identifies the relationship will suffice.

1.6.1 The IsA Relation

Suppose a Message is a kind of Stri ng. That is, an object of type Message can be used
wherever a St r i n g object is required.
Section 1.6.1 The IsA Relation 49

class String {
I I ...
public: ( String)
I I ...
};

class Message: public String {

I I ...
pub 1 i c: Message
I I .,.
};

(a) Elided Class Definitions (b) Notational Representation

Figure 1-16: The IsA Relation

As we can see from the definitions of Figure 1-16a, class Message inherits from class
Stri ng, and an arrow is used to denote this relationship in Figure 1-16b:

IsA
D

That is, D-----1.~B means that "D is a kind of B" and that "D inherits from B."

The direction of the arrow is significant; it points in the direction of implied depen-
dency. Class 0 depends on B because 0 is derived from B. B must come first in order
for 0 to name B as a base class:

class B { 1* ... *1 };
class 0 public B { 1* .0. *1 };

Often you will see the arrow pointed in the opposite direction, which can be mislead-
ing. An arrow shows an asymmetric relationship between two entities denoted by its
label (in this case "IsA"). To draw the arrow the other way, we would logically have to
call.the relation something else, such as "Derives" or "Is-A-Base-Class-Of":

( D ) ........~----...;D~e~riv..;......;;;..es~--tC B ) (less useful)

This alternative notation is less desirable because the arrow points in the direction
opposite to that of implied dependency.
50 Preliminaries Chapter 1

Because analyzing physical dependencies is essential to good design, we adopt the

notation assuming the IsA label and point our arrows in the direction of implied
dependency. Figure 1-17 provides one last illustration of inheritance notation using
the classic shape example.

Shape Shape

IsA

Square (Square )

(a) Incorrect Notation (b) Less Useful Notation

Shape

IsA

Square

(c) Correct Notation

Figure 1-17: Notations Used to Indicate Derivation

1.6.2 The Uses-In-The-Interface Relation

Whenever a function names a type in its parameter list or names a type as a return value,
that function is said to use that type in its interface. That is, a type is used in the interface
of a function if the type name is part of the function's return type or signature. 14

DEFINITION: A type is used in the interface of a function if the type

is referred to when declaring that function.

14 Exclude the possible use of typedefs, which are just synonyms.

Section 1.6.2 The Uses-In-The-Interface Relation 51

For example, the free function

int operator==(const IntSet&, const IntSet&);

clearly makes use of class I nt Set in its interface. This function happens to return an
i nt, so i nt also would be considered part of this function's interface. However, fun-
damental types are ubiquitous and omitted from such consideration in practice.

DEFINITION: A type is used in the (public) interface of a class if the

type is used in the interface of the (public) member function of that
class.

There are three levels of logical access for classes in C++: pub 1 i c, protected, and
pr i va teo The public interface of a class is defined as the union of the interfaces of the
public member functions of that class. The protected interface of a class is defined
similarly_ In other words, when a (pub 1 i c) member function of class B uses class A in
its interface, we say that class B uses class A in B's (pub 1i c) interface. IS For example,
the constructor for c las sIn t Set I t e r, I n t Set I t e r ( con s tIn t Set &) uses clas s
I ntSet in its interface; therefore I ntSet is used in the interface of I ntSet Iter.

The Uses-In-The-Interface relation is one of the most common and is denoted by

o Uses-In-The-Interface

That is, BO A means "B uses A in B's interface." We will sometimes be

sloppy and say "B uses A in its interface," but we will always mean that B uses A in
B's interface, and never that B uses A in A's interface.

You can think of the 0 symbol as an arrow with its tail at the bubble and the
head missing (or as a conductor's baton pointing at a member of the orchestra). The
direction of the implied arrow is important-it points in the direction of implied
dependency. That is, if B uses A, then B depends on A and not vice versa. (We will talk
more about implied dependency in Section 3.4.)

15 The interaction between friendship and the Uses-In-The-Interlace relation is discussed in Section 3.6.1.
52 Preliminaries Chapter 1.

Figure 1-18 shows the logical view of the i ntset component, including the Uses-In-
The-Interface relation among the logical entities (classes and free operator functions)
defined there. The figure reflects that I n t Set I t e r and both free operators use I n t Set
in their respective interfaces.

IntSet

intset
Logical View

Figure 1-18: The Uses-In-The-Interface Relation within the i ntset Component

The U ses-In-The-Interface relation is a valuable tool for both logical and physical
design. This notation is most useful when confined to logical entities (classes and free
operators) at file scope. Free operators are frequently omitted from logical diagrams
in order to reduce notational clutter.

The actual logical interface for a class can be quite large and complex. Often the prop-
erty we are most interested in exhibiting is one of intrinsic dependency rather than
detailed usage. The set of types used in the interface of a class is more stable (i.e., less
likely to change during development and maintenance) than the set of types used by
any particular member function. The more abstract usage characteristics of the class
taken as a whole are, therefore, more resilient to small changes in the logical interface
than are the usage characteristics of its individual member functions.

1.6.3 The Uses-In-The-Implementation Relation

The U ses-In-The-Implementation relation augments a designer's ability to express

logical dependencies abstractly. The notation that one logical entity will make use of
another in its implementation (even though it is not used in its interface) can be very
helpful in analyzing the underlying structure of a design. Like its counterpart, U ses-
In-The-Implementation suggests a physical dependency between two logical entities.
 The Uses-In-The-Implementation Relation 53
Section 1.6.3

Architects can make good use of this information as they refine high-level designs and
cast them into discrete physical components.

DEFINITION: A type is used in the implementation of a fQnction if

the type is referred to in the definition of that function.

Consider the following implementation of the free function operator==, which

assumes that the members of equivalent I nt Set objects are always returned by the
iterator in the same order:'

int operatar==(canst IntSet& left, canst IntSet& right)

{
IntSetlter lit(left);
IntSetlter rit(right);
for (; lit && rit; ++lit, ++rit) {
if (lit() != rit()) {
return 0;
}
}
II At least one of lit and rit now evaluates to o.
return lit == rit;
}

.
In the above implementation, two iterators are created: one for each In t Set argument.
The body of the for loop is entered only while both iterators refer to valid set
elements. With each iteration through the loop, integers at corresponding positions in
the sets are compared. If any such comparison fails, then the sets are immediately rec-_
ognized as being not equal. On exit from the for loop, both of the following condi-
tions must be true:

1. At least one of the iterators has reached the end of its set and is now
invalid.

2. No corresponding entries of the set have been found to be unequal.

The two I ntSet objects are equal if and only if both iterators are now invalid.

Note that operator==(const IntSet&, const IntSet&) isnota friend of class

I ntSet. Therefore any efficient implementation of this operator must take advan-
tage of class I nt Set I t e r. The Uses relationship between the implementation of
54 Preliminaries Chapter 1

operator== and class IntSetlter produces an implied dependency of operator==

on class In t Se tIt e r. Because IntSetIter is used in the implementation of this opera-
tor but not in its logical interface, we employ a slightly different symbol to denote the
relationship:

Uses-In-The-Implementation
•
That is, B -e--- A means that A is used in the implementation of B.

intset
Logical View

Figure 1-19: Both Kinds of Uses Relations Within the; ntset Component

Figure 1-19 again shows us the logical view of the ; ntset component along with both
kinds of uses relationships. In particular we see that

int aperatar==(canst IntSet&, canst IntSet&)

uses class I nt Set in its interface and class In t Set I t e r in its implementation.
Although 0 per a tor! = is shown implemented symmetrically to 0 per at 0 r==, _
ope rat 0 r ! = would probably be implemented in terms of 0 per at 0 r== in practice.

If an object is used in the interface of a function, it is automatically considered to be

used in the implementation of that function. We can therefore conclude from seeing
the • symbol that the indicated usage is not in the interface. For example,
we can infer directly from Figure 1-19 that ope ra tor! = does not use I ntSet I te r in
its interface.
Section 1.6.3.1 Uses 55

DEFINITION: A type is used in the implementation of a class if that

type (1) is used in a member function of the class, (2) is referred to in
the declaration of a data member of the class, or (3) is a private base
class of the class.

A class can use another type in its implementation in several ways. As we will see in
Section 3.4,- the particular way in which our class uses a type will affect not only how
our class depends on that type but also to what extent clients of our class will be
forced to depend on that type. For the time being, we simply exhibit the ways in
which a class can use a type in its implementation:

DEFINITION:
Specific kinds of the Uses-In-The-Implementation Relationship:
Name Meanin&
Uses The class has a member function that names the type.
HasA The class embeds an instance of the type.
HoldsA The class embeds a pointer (or reference) to the type.
WasA The class privately inherits from the type.

1.6.3.1 Uses

If any member function of a class (including a private member) names a type in either
its interface or its implementation, that type is considered to be used in the logical
implementation of the class.
/'
56 Preliminaries Chapter 1

class Crook {
private:
va; d bribe();
// ...
};

class Judge;

voi d Crook:: bri be() {

Judge *bad = 0;
/ / ...
};

( Crook )_....--u_s_e_s-_In_-_T_h_e-_I_m-=..p_Ie_m_e_ll_ta_ti_o_n--f( Judge)

Figure 1-20: Crook Uses Judge

Figure 1-20 illustrates that since type J ud9 e is named in the body of a member func-
tion (bri be) of class Crook, Judge is used in the implementation of Crook. In other
words, class Crook uses Judge.

1.6.3.2 HasA and HoldsA

Another form of usage occurs when a class, X, embeds a (private) data member of
type T. This kind of internal usage is commonly referred to as HasA. Even if,class X
contains a data member whose type is merely derived (in the C-Ianguage sense) from
T (e.g., T* or T&), T is still considered to be used in the logical implementation of X.
We will occasionally refer to this kind of internal usage as HoldsA.

class Tower { /* ... */ };

class Cannon; II declaration only

class BattleShip {
Tower d_controlTower;
Cannon *d_replaceableForward8attery_p;
Cannon& d_fixedAftBattery;
// ...
};

Battleship
(RasA) (Holds A)
Uses-In-The-Implementation Uses-In-The-Implementation
Cannon

Figure 1..21: Battl eshi p HasA Tower and HoldsA Cannon

section 1.6.3.3 WasA 57

Figure 1-21 shows a class definition for Tower and a class declaration for Cannon.
Both of these types are used in the implementation of class Bat t 1e s hip. In particular,
Ba ttl es hip RasA Towe rand Ba ttl es hip RoldsA Ca n non. We make no distinction in
the symbolic notation we use: both HasA and HoldsA are indicated with the usual
• notation .

1.6.3.3 ~as)l

Inheriting privately from a type is yet another way to use that type in the logical
implementation of a class. Private inheritance is an implementation detail of the
derived class. From a logical point of view, a private base class (like a private data
member) is invisible to clients. Private inheritance is a technique that can be used to
propagate only a subset of the attributes of its base class. This seldom-used relation
has been affectionately termed WasA, and is illustrated in Figure 1-22.

class Battleship { 1* ... *1 };

class Shop { 1* ... *1 };
class Exhibit: II declaration only

class ArizonaMemorial : private Battleship {

Shop d_giftShop;
Exhibit *d_current_p;
Exhibit& d_default;
I I ...
};

Battleship
(Was A)
U ses-In-The-Implementation

ArizonaMemorial

(HasA) (HoldsA)
Uses-In-The-Implementation U ses-In-The-Implementation

Shop

Figure 1-22: Ar; zonaMemo r; a 1 WasA Bat t 1 es hi P

Figure 1-22 shows a class definition for Bat t 1 e s hip that acts as a private base class
for Ar i zan aMemo ri a 1 . Once in active service, the battleship Arizona was one of the
58 Preliminaries Chapter 1

casualties of the 1941 bombings of Pearl Harbor. The Arizona is now a museum with
a gift shop and exhibits.

Although private inheritance is an implementation detail, public and protected inherit-

ance are not. Inheritance increases the set of types that are compatible with the base
type. Nonprivate inheritance therefore introduces information that is programmati-
cally accessible by clients. The unique properties of public and protected inheritance
make them worthy of their own notation, as presented in Section 1.6.1.

We have now reviewed all of the logical notation we need to get down to the serious
business of physical design. The logical and physical aspects of design are tightly
coupled. Each of the logical relations-IsA, Uses-In-The-Interface, and Uses-In-The-
Implementation-implies a physical dependency between logical entities. As we will
see in Chapter 3, it is ultimately these logical relations that dictate the physical inter-
dependencies within our system.

1.7 Inheritance versus Layering

In the context of object-oriented design, when someone mentions the word hierarchy,
many people think inheritance. Inheritance is one form of logical hierarchy-layer-
ing is another. By far, the more common form of logical hierarchy in object-oriented
design results from layering.

DEFINITION: A class is layered on a type if the class uses that type

substantively in its implementation.

Layering is the process of building on smaller, simpler, or more primitive types to

form larger, more complex, or more sophisticated types. Often layering occurs
through composition (e.g., RasA or HoldsA), but any form of substantive use (i.e.,
any use that would induce a physical dependency) qualifies as layering.

Instances of a layered type are often not programmatically accessible to clients via the
interface of the higher-level object. The connotation is that the primitive type is at a
lower level of abstraction. For example, a person has a heart, a brain, a liver, and so
on, yet these layered organ objects are not part of the public interface of most healthy
Section 1.8 Minimality 59

people. An object as simple as a list is often implemented as a collection of links, yet

the Lin k class itself is not used in the interface of most well-written Lis t classes.

Inheritance, along with dynamic binding, distinguishes object-oriented languages

(such as C++) from object-based languages (such as Ada) that support user-defined
types and layering but not inheritance. 16 The semantics of inheritance are quite differ-
ent from those of layering. For example, the public functionality of both base and
derived classes is accessible by clients. 17 With inheritance, the more specialized or
concrete class depends on the more general or abstract class(es). With layering, the
class at a higher level of abstraction depends on the class(es) at a lower level of
abstraction.

Brain Brain) Liver

(Bad Idea)

(a) Layering (b) Multiple Inheritance

Figure 1-23: Layering versus Multiple Inheritance

Layering is an important and often underdeployed weapon in the arsenal of the object-
oriented designer. It is not uncommon for novice programmers to attempt to use
inheritance where layering is indicated. Figure 1-23 shows two examples of logical
hierarchy. In both cases, Per son implicitly depends on He art, Bra in, and Li ve r in
order to do its job. Layering is clearly the correct approach here because a Person is
not a Hea rt, a Bra in, or aLi ver. Instead, a Person has a Hea rt, a Bra in, and a
Liver. Furthermore, these organs must not be exposed in the interface of a Person.
With layering, a client need not be subjected to the interfaces of these internal details.

1.8 Minimality

Some class authors want their classes to be all things to all people. Such classes
have been referred to, affectionately, as Winnebago classes. This very common and
seemingly noble desire is cause for concern. As developers, we must remember that

16 See hooch, Chapter 2, p. 39.

17 Note: private inheritance is a fonn of layering.
60 Preliminaries Chapter 1

just because a client asks for an enhancement doesn't mean that it is appropriate for
our class. Suppose you are the author of a class and each of 10 clients asks you for a
different enhancement. If you agree, two things will happen:

1. You will have to implement, test, and document 10 new features that you
did not originally consider part of the abstraction that you were trying to
implement (which in itself is a symptom of a problem).

2. Each of your 10 clients will be given 9 new features that they did not ask
for and probably don't need or want.

Every time you add a feature to please one person, you disrupt and potentially annoy
the rest of your client base. It has happened that classes that were originally light-
weight and very useful have, over time, become so bloated that instead of being good
for everything, they have become, quite literally, good for nothing.

Notice that in Section 1.5 we chose to disallow explicitly the possibility of initializa-
tion or assignment for instances of both I n t Set and I n t Set I t e r by declaring the
respective member functions private. Making a copy of a collection can result in non-
trivial development effort, and such functionality for iterators is rarely needed in prac-
tice. We can defer the implementation and testing of superfluous functionality unless
or until a need for that functionality presents itself. Deferring implementation is also
one way to keep our options open. Not only does it require less work to implement,
test, document, and maintain software, but by deliberately not supplying functionality
prematurely, we commit to neither its behavior nor its implementation. In fact, not
implementing functionality can improve usability. For example, making the copy con-
structor private prevents inadvertently passing an object by value-a technique used
in the iostream package. 18

This minimalist approach of making components sufficient but not necessarily com-
plete applies to large projects under development where the users of the component
are "in-house" or in a position to request and receive additional functionality quickly
should it tum out to be needed. The most extreme case occurs where the component is
highly specialized and the author is the only intended user. In that case, implementing
any unneeded functionality is probably unwarranted. Of course,omitting the imple-

18 Passinguser-defined types by value is a common cause of unnecessary performance degradation

(see Section 9.1.11).
Section 1.9 Summary 61

mentation of functionality intrinsic to an abstraction would not make sense for, say, a
commercial component library where the users are paying customers and will expect
robust and fully functional objects. This issue is not black and white; between the two
extremes lies a spectrum that corresponds to how widely a component will be used. In
evaluating the trade-offs, remember to consider that functionality is invariably easier
to add than to remove.

1.9 Summary

Large C++ programs reside in more than a single source file. Partitioning programs
into separate translation units makes recompilation more efficient and reuse possible.

Although most C++ declarations can be repeated in a given scope, there must be
exactly one definition of every object, function, or class used in a C++ program.

Definitions with internal linkage are confined to a single translation unit and cannot
affect other translation units unless placed in a header file. Such definitions can exist
at file scope in . c files without affecting the global (symbol) name space.

Definitions with external linkage can be used to resolve undefined symbols in other
translation units at link time. Placing such definitions in header files is almost cer-
tainly a programming error.

Typedef declarations are only aliases for types and provide no additional compile-
time type safety.

Assert statements can be used effectively to detect coding errors during development
without affecting program size or runtime performance in the production version of a
product.

In this book we adopt the following style conventions:

• Type identifier names begin with an uppercase letter.

• Functions and data begin with a lowercase letter.

• Multi-word identifier names capitalize the first letter of the second and
subsequent words.
62 Preliminaries Chapter 1

• Constants and macros are all uppercase (with words separated by a single
underscore) .
•
• Class data members are prefixed by d_ (or s_ for static members).

• Class member function will be organized according to creator, manipulator,

and accessor categories.

• Private details will precede the public interface in class definitions (primarily
to emphasize their presence in the header file).

The iterator design pattern is used to sequence over the parts, attributes, or sub-
objects of some primary object. An iterator is declared to be a f r i end of the primary
object, and its definition should reside in the same header file as that object. The
iterator notation used in this book tersely conforms to a for-loop model.

Object-oriented design lends itself to a rich set of logical notations. In this text,
however, we will limit ourselves to three:

IsA o U ses-In-The-Interface • Uses-In-The-Implementation

The orientation of each symbol (shown here from left to right) should be consistent
with its label and point in the direction of implied dependency. There are a few special
names for some particular kinds of Uses-In-The-Implementation (Uses, RasA,
HoldsA, and WasA); however, the notation used to represent each of these variations
is the same.

Inheritance and layering are two forms of logical hierarchy. Layering is by far the
more common, often involving an implementation-only dependency. Layering, spe-
cifically composition, is preferable to derivation when the class in question cannot
sensibly be thought of as a kind of the proposed base class(es). Finally, extending the
functionality of a single class in response to several clients often results in a class that
is overweight and undesirable. For classes that are not widely used, implementing
excessively complete functionality can unnecessarily increase development time,
maintenance cost, and code size. Deferring the implementation of functionality that is
not yet needed reduces development time while keeping options open. On the other
hand, commercial component libraries are expected to be fully functional and robust.
 Ground Rules

. This chapter describes a modest collection of fundamental design rules that have
proved useful in practice and that serve as framework for discussing the material sur-
rounding more advanced rules presented later in this book. These fundamental rules
address basic practices such as restricting member data access and reducing the num-
ber of identifiers in the global name space. In particular, we examine what types of
constructs can safely be placed at file scope in a header file. The need for both internal
and redundant external include guards will be established. This chapter concludes
with a discussion of what constitutes adequate documentation (such as explicitly iden-
tifying behavior that is undefined), followed by a short list of identifier-naming con-
ventions.

Overview

The beauty of any fine art comes not only from creativity but also from discipline. So
it is with programming. C++ is a large language, and there is ample room to be cre-
ative with it. However, the design space is so big that without discipline-that is,
without some modest constraints on the design structure-large projects can easily
become intractable and unmaintainable. These constraints are presented in the form of
design rules, guidelines, and principles.

Design Rules: Experience tells us that certain coding practices that are perfectly legal
in C++ simply should never be used in a large-project environment. Recommenda-
tions that flatly proscribe or require a given practice without exception are referred to
in this book as design rules. Verifying adherence to these rules cannot be a subjective
64 Ground Rules Chapter 2

process. Design rules must be sufficiently precise, specific, and well defined so that
complying with these rules can be verified objectively. To be effective, design rules
must lend themselves to impersonal, mechanical verification via automated tools.

Guidelines: Experience also tells us that certain other practices should be avoided
wherever possible. Suggested practices of a more abstract nature for which exceptions
are sometimes legitimately made are called guidelines. Guidelines are like rules of thumb
to be followed unless other, more compelling, engineering reasons dictate otherwise.

Principles: There are certain observations and truths that have often proved useful
during the design process but must be evaluated in the context of a specific design.
These are referred to as principles.

Gaining consensus on software coding standards among independent programmers

can be quite challenging. Every programmer has his or her own extended set of con-
ventions. I impose many more rules on myself than I could possibly share with you,
but they mostly involve style, not substance. If we can agree on the 10 percent of the
rules that buy us 90 percent of the real benefit, we will be doing very well indeed.

This book contains many recommendations. In this chapter I present a set of very
basic design rules that I call ground rules, explaining and (I hope) justifying each rule
as I go. You may not agree with all of them at first, but over time they have proved
both workable and effective for very large projects.

I have subdivided design rules into two distinct categories: major and minor. Major
design rules refer to practices that must always be followed. Deviating from a major
design rule is likely to affect the quality not only of the offending component, but also
of other components within the system. Even infrequent violations could undermine
the success of a large project. Throughout this book, I have assumed that major design
rules are never violated. As always, never never means NEVER. If extraordinary cir-
cumstances and common sense dictate that one or more major design rule'S be vio-
lated, it is incumbent upon developers to fully understand and appreciate the
implications and possible consequences of their actions. Minor design rules refer to
practices that are strongly recommended but not necessarily critical to a project's
overall success-for example, issues involving constructs that are used only in the
implementation, are unlikely to affect other developers, and are otherwise relatively
contained and easy to fix in isolated instances. Draconian adherence to minor design
Section 2.2 Member Data Access 65

rules is not critical because (unlike adherence to major rules) the cost of a project
increases only incrementally with each minor rule violation.

Because it is not expected that there will ever be an engineering reason to violate any
design rule (major or minor), any design rule that proscribes one approach must offer
a suitable alternative that will work in all cases.

2.2 Member Data Access

Encapsulation is a term used to describe the concept of hiding implementation details

behind a procedural interface. Comparable terms include information hiding or data
hiding. Directly accessing a data member of a class violates encapsulation.

Major Design Rule ,

Keep class data members private.

Consider the definition of class Re eta n 9 1e in Figure 2-1. This Re eta n9 1 e is defined
by providing two Poi nt objects (see Figure 1-1) that identify its lower-left and upper-
right comers. Since this particular implementation of Re eta n9 1e stores these Poi nt
values internally, we might be tempted to make the data members public to avoid sup-
plying manipulator (i.e., set) and accessor (i.e., get) functions for each.

II rectangle.h
#ifndef INCLUDED_RECTANGLE
#define INCLUDED_RECTANGLE

class Rectangle {
public:
Point d_lowerLeft; II bad idea (public data)
Point d_upperRight; II bad idea (public data)
public:
II CREATORS
Rectangle(const Point& lowerLeft, canst Point& upperRight);
Rectangle(const Rectangle& rect);
,...,Rectangle();

II MANIPULATORS
Rectangle& operator=(const Rectangle& rect);
void moveBy(const Point& delta);
II
66 Ground Rules Chapter 2

II ACCESSORS
int area() const;
I I ....
};

II
inline
void Rectangle::moveBy(const Point& delta)
{
d_lowerLeft += delta;
d_upperRight += delta;
}

II
ffendif

Figure 2-1: Poor (Unencapsulating) Rectangl e Class Interface

Now consider the impact on clients when we discover that Rectangl e objects are fre-
quently moved. To improve performance, we might try changing the representation of
Recta ng 1 e objects. For example, instead of storing the absolute location of the upper-
right comer, we might represent that value implicitly by storing its position relative to
the lower-left comer:

class Rectangle {
public:
Point d_lowerLeft; II same purpose as in Figure 2-1
Point d_upperRightOffset II new "relative" representation

With this new representation, the moveBy member function can be implemented in one
line instead of two because the relative position of the upper-right comer with respect
to the lower-left is not affected by the move:

inline
Rectangle::moveBy(const Point& delta)
{
d_lowerLeft += delta;
}

The location of the upper-right comer is no longer stored in the Rectangl e object and
therefore must be calculated when needed:

void clientCconst Rectangle& rect)

{
Point upperRight - rect.d lowerLeft + rect.d_upperRightOffset;
// ...
}
Section 2.2 Member Data Access 67

Any clients who previously accessed the d_u p per Rig h t data member directly will
now be forced to rework their code. Component reuse compounds this problem. If a
class defining public data is shared among executables, then changing the data repre-
sentation of a single class could necessitate modifying the source code for any number
of separate programs.

DEFINITION: A contained implementation detail (type, data, or

function) that is not accessible or detectable programmatically
through the logical interface of a class is said to be encapsulated by
that class.

Encapsulation is an important tool of object-oriented design. 1 By encapsulation we

mean that a collection of low-level information is brought together, potentially to
interact in a tightly coupled, intimate way. Information hiding is then applied to limit
the external world from interacting with details that are not germane to the abstraction
the class is supposed to help implement.

Keeping all data members private and providing the appropriate accessor and
manipulator functions, as shown in Figure 2-2, leaves us free to change the internal
representation without forcing our clients to rework their code. The implementation
of getUpperRi ght() could have been modified to compute that value on demand
without changing its logical interface.

Besides maintainability, there are reasons not to have public data members. For exam-
ple, the values of data members in a class are rarely independent. Direct (writable)
access to data (such as d_a rea in Figure 2-2) could easily leave an object in an incon-
sistent state. Providing only a functional interface grants class authors the level of
control necessary to ensure the integrity of their objects. Providing manipulator and
accessor functions also affords developers the opportunity to insert temporary code
(e.g., print statements for debugging, reference counts for performance tuning, and
assert statements for reliability).2

1 booch, Chapter 2, pp. 49-54.

2 For a further discussion of why to avoid public data, see meyers, Item 20, pp. 71-72.
68 Ground Rules Chapter 2

II rectangle.h
#ifndef INCLUDED_RECTANGLE
#define INCLUDED_RECTANGLE

class Rectangle {
Point d_lowerLeft; II Yet another representation!
int d_width; II Fortunately, these data members are private.
int d_height;
int d_area; II Store this redundantly to improve performance.
publ ic:
I I CREATORS
RectangleCconst Point& lowerLeft, const Point& upperRight);
RectangleCconst Rectangle& rect);
-RectangleC);

II MANIPULATORS
Rectangle& operator=(const Rectangle& rect);
void moveBy(const Point& delta);
II

II ACCESSORS
int area() const;
Point getLowerLeftC) canst;
Point getUpperRight() const:
};

I I ...

inline
void Rectangle::moveByCconst Point& delta)
{
d_lowerLeft += delta;
}

I I ...

inline
Point Rectangle::getUpperRight(const Point& delta) canst
{
return d_lowerLeft + PointCd_width, d_height);
}

II

Figure 2-2: Better (Encapsulating) Rectangl e Class Interface

Note that public access to data members of a 5 t rue t (or class) that itself is entirely
hidden (either privately within another class or locally within a . c file) is a separate
matter not covered by the above rule (see Sections 6.4.2 and 8.4). When data
 The Global Name Space 69
section 2.3

members are not private, it is preferable to denote the deliberate lack of encapsulation
by using the keyword 5 t rue t instead of c 1 ass.

Some people advocate the use of protected data to facilitate arbitrary access from a
derived class. But from a maintainability perspective, pro tee ted access is like pub-
1 i c access because anyone who wants to get at protected data can do so with only the
modest additional effort of deriving a class. Unlike friendship, which explicitly
denotes who has access to private details, making class data protected results in an
unbounded breach of encapsulation.

The same arguments that applied to the public interface also apply to the protected
interface. Base-class authors can preserve maintainability by treating their protected
and public interfaces as separate but equally important. Keeping all member data pri-
vate and supplying the appropriate protected functions will enable the base-class
implementation to change independently of any derived classes.

2.3 The Global Name Space

For projects of even moderate size involving more than a single developer, there is a
danger of name collisions when independently developed parts are integrated into a
single program. The severity of the problem grows exponentially with system size,
and is exacerbated when the collisions result from integrating software provided by
third-party vendors.

There are various ways to pollute the global name space, some more onerous than
others. All of them are counterproductive in a large system environment. We now
address several of these issues independently and conclude this section with a design
rule that describes what kinds of declarations and definitions may exist safely at file
scope in C++ header files.

2.3.1 Global Data

It has been said that global variables are like a cancer: you can't live with them, but
once established, they are often impossible to cut out. We can always get away with-
out using external global variables in a new C++ project. Exceptions to this rule might
involve access in a baroque program (such as Lex or YACC) that communicates via
global variables or perhaps within embedded systems.
70 Ground Rules Chapter 2 .

Major Design Rule

Avoid data with extemallinkage at file scope.

File scope data with extemallinkage risks collision with global names in other trans-
lation units (whose authors were egocentric enough to believe that they, too, owned
the global scope). But name pollution is only one of the many ways in which global
variables damage a program. Global variables tie objects and code together in ways
that make it virtually impossible to reuse translation units selectively in other pro-
grams. Debugging, testing, and even understanding systems that make liberal use of
global variables can become overwhelmingly costly in large projects.

Provided that you are not forced to use a system that already requires using global
variables in its interface, there are a couple of simple transformations that can unglo-
balize these variables:

1. Put all global variables in a structure.

2. Then make them priva~e and add static access functions.

Suppose you had the following global variables:

int size;
double scale;
canst char *system;

These variables can be removed from the global name space by enclosing them in a
s t rue t and making them s tat i c members of that structure: 3

struct Global {
static int s_size; II bad idea (public data)
static double s_scale; II bad idea (public data)
static const char *s_system; II bad idea (public data)
};

3 meyers, Item 28, pp. 93-95.

Section 2.3.1 Global Data 71

Remember, of course, to define these static data members in the corresponding . c file.
Now, instead of accessing the global variables using

s i z e, sea 1e, or s y s tern

you would use

Glob a1 : : S _ S i z e, Glob a 1 : : S _ sea 1e t or Glob a 1 : : S _ S Ys t em

,

respectively. The probability of collisions is now reduced to the probability of colliding

with a single class name (and it is easy to address even that possibility using the
techniques discussed in Section 7.2).

Although we have solved the global name space problem, we have not done all that
we should. Experience shows that just as with non-static (Le., instance-specific) mem-
ber data, directly accessing static (Le., class-specific) member data makes large sys-
tems profoundly more expensive to maintain. If we were to change the exported data
type of a member (e.g., s_s i ze) from i nt to daub 1e, that would be an interface
change; all clients would be affected regardless of what we do. But we may decide to
change the implementation of s_s i ze to a computed value based on other, more prim-
itive values (such as s_wi dth and s_hei ght). Providing static function members to
access (and manipulate) static data members allows us to make such local changes
without perturbing clients of the global scope.

The next step is to eliminate the public data by making Glob a 1 a class and providing
static manipulator and accessor methods, as illustrated in Figure 2-3. Class G1a b a1
now acts as a logical module accessible from anywhere in the program. Because all
the interface functions are static, there is no need to instantiate an object in order to
use this class. Declaring the default constructor private and leaving it unimplemented
enforces this usage model.

To achieve a flexible design, we should be careful not to overuse global state informa-
tion. The mere fact that we expect to have only a single instance of an object is not suffi-
cient reason to make it a module instead of an instantiatable class. Globally accessible
modules make sense when they correspond to inherently unique entities (such as a sys-
tem console) or for system-wide constants (such as those found in 1 i mi ts . h) that are
not dictated by a particular application (see Section 6.2.9). Global modules are best
avoided when other, more localized (e.g., object-based) implementation will suffice. 4
72 Ground Rules Chapter 2

class Global {
static int s_size;
static double s_scale;
static const char *s_system:

private:
II NOT IMPLEMENTED
Global(); II prevent inadvertent instantiation

public:
II MANIPULATORS
static void setSize(int size) { s size = size; }
static void setScaleCdouble scale) { s_scale = scale; }
static void setSystem(const char *system) { s_system = system; }

II ACCESSORS
static int getSize() { return s_size; }
static double getScale() { return s_scale; }
static canst char *getSystem() { return s_system; }
};

Figure 2-3: Logical Module Containing Global State Information

2.3.2 Free Functions

Free functions, too, can be a threat to the global name space, especially when they do
not involve any user-defined type in their argument signature. If a free function is
defined with internal linkage in a . h file or with external linkage in a . c file, it may
collide with another function definition with the same name (and signature) during
program integration. Operator functions are an exception.

l\tlajor Desigll Rllie .

Avoid free functions (except operator functions) at file scope in . h

files; avoid free functions with extemallinkage (including operator
functions) in . c files.

4 See the Singleton design pattern in gamma, Chapter 3, , pp. 127-134.

 Enumerations, Typedefs, and Constant Data 73
section 2.3.3

Fortunately, free functions can always be grouped into a utility class (s t rue t) con-
taining only static functions. The resulting cohesion is not necessarily optimal, but it
does reduce the likelihood of global name collisions. Here's an example:

int getMonitorResolution(): I I bad idea

void setSystemScaleCdouble scaleFactor); I I bad idea
int isPasswordCorrectCconst char *usr, canst char *psw); II bad idea

The above free functions could always be replaced by the following static methods:

struct SysUt i 1 {
static int getMonitorResolutionC);
static vaid setSystemScaleCdouble scaleFactor);
static int isPasswordCarrect(canst char *usr, canst char *psw);
};

The only symbol at risk would be the class name Sy s Uti 1 .

Unfortunately, free operator functions cannot be nested inside classes. Thisis not a
serious problem because free operators require at least one of their arguments to be a
user-defined type. Hence the likelihood of free operators colliding is remote, and such
collisions are typically not a problem in practice.

2.3.3 Enumerations, Typedefs, and Constant Data

Enumerations, typedefs, and (by default) file scope const data all have intemallink-
age. People often declare constants, enumerations, or typedefs at file scope in header
files. This is a mistake.

Major Desigll Rule

Avoid enumerations, typedefs, and constants at file scope in· . h files.

Because C++ fully supports nested types, enumerations can be defined (and typedefs
declared) within the scope of a class without conflicting with other names in the
global name space. By choosing a more limited scope in which to define an enumer-
ation, you ensure that all enumerators of that enumeration become similarly scoped
and thus will not conflict with other names defined outside that scope.
74 Ground Rules Chapter 2

Consider the following enumerations:

II paint.h
enum Color { RED, GREEN, BLUE, ORANGE, YELLOW}; II bad idea
II juice.h
enum Fruit ( APPLE, ORANGE, GRAPE, CRANBERRY}; II bad idea

These two enumerations were probably not written by the same developer, yet it is
quite possible that they could someday be included in the same file, resulting in an
ambiguity, ORANGE, that cannot be resolved!

II picture.c
#include "picture.h"
#include "paint.h"
#include "juice.h"

If these two enumerations are instead defined within separate classes, one can easily
use scope resolution to resolve the ambiguity: Pai nt: : Orange or Jui ce: : Orange.

For similar reasons, typedefs and constant data should also be placed within class
scope in header files. Most constant data is integral, and nested enumerations work
well to provide integral constants within the scope of a class. Other constant types
(e.g., doubl e, Stri ng) must be made static members of the class and initialized
within the. c file:

II array.h II array.c
#ifndef INCLUDED_ARRAY #include "array.h"
#define INCLUDED_ARRAY

class String; #include "str.h" II class String

class Array {
enum { DEFAULT_SIZE = 100 };
static canst double DEFAULT_VALUE; double Array::DEFAULT_VALUE = 0.0;
static canst String DEFAULT_NAME; String Array::DEFAULT_NAME = " " ;

II I I ...
};

#endif

In large projects, aside from the global name collisions, there is a very real problem
with even finding enumerations, typedefs, and constants at file scope. Nesting a
section 2.3.4 Preprocessor Macros 75

typedef within a class forces the name to be fully qualified (or the declaration to be
inherited), making it relatively easy to find. The same reasoning applies to enumera-
tions, but even stronger arguments for nesting enumerations within classes have
already been presented.

2.3.4 Preprocessor Macros

There is almost no need for macros in C++. They are useful for include guards (see
Section 2.4), and in a very few cases their benefits outweigh their problems in a . c file
(most notably, when used to achieve conditional compilation for portability or debug-
ging). But in general, preprocessor macros are inappropriate for production software.

Major Design Rule

Avoid using preprocessor macros in header files except as include

guards.

The preprocessor is not part of the C++ language; its basis is completely textual, mak-
ing macros painfully hard to debug. Although macros can make code easier to write,
their free form often makes code much harder to read and understand. Consider the
following code fragment:

#define glueCX,Y) X/**/Y

glueCpri,ntf) (IiHello World");

How would you tell your debugger, browser, or other automated tool to deal with the
above at the source level?

As bad as macros are in . c files, there are even stronger software engineering reasons
for keeping macros out of header files. Take the case of defining a preprocessor con-
stant using #defi ne in a header file. Since macros are not part of C++, they cannot be
placed inside the scope of a class. Any file that includes a header file with a #defi ne
will take on that definition.
76 Ground Rules Chapter 2

Suppose thei rcode. h defines a constant value GOOD as a preprocessor constant:

II theircode.h II ourcode.c
#ifndef INCLUDED_THEIRCODE #include "ourcode.h"
#define INCLUDED_THEIRCODE #include "theircode.h"

I I ... I I ...

#define GOOD 0 II bad idea int OurClass::aFunction()

{
I I ... enum { BAD = -It GOOD = 0 } status - GOOD;

#endif I I ...

return status;
};

II

When file ou rcode. c is compiled, the compiler first calls the preprocessor. Even
though GOOD is defined within the protective scope of a function, it is not safe from the
preprocessor, which mercilessly replaces the enumerator GOOD with the literal integer 0:

I I ...

int OurClass::aFunction
{
enum { BAD = -It 0 = 0 } status - 0;

I I ...

return status;
}:

When the compiler encounters the enumeration, it spits out Synta x Er ro r, but you won't
know why until you have spent an eternity "grepping" through . h files looking to see
who has IFdefi ne'd one of your enumerators. Notice that this problem would not have
section 2.3.5 Names in Header Files 77

occurred if the preprocessor symbol had instead been either a canst or an enum at file
scope (which, by the way, are also design-rule violations according to Section 2.3.3):

II theircode.h II theircode.h
#ifndef INCLUDED_THEIRCODE #ifndef INCLUDED_THEIRCODE
#define INCLUDED_THEIRCODE #define INCLUDED_THEIRCODE

I I ... I I ...

canst int GOOD = 100; II bad idea enum { GOOD = lOa}; II bad idea
II file-scope constant data II file-scope enumerated value

I I ... I I ...

#endif #endif

Preprocessor macros can also be used to implement templates in cases where that
C++ language feature is missing or inadequately implemented. If macros are used for
this purpose, then macro functions will appear in header files. There are ways to
approach this problem, other than resorting to macros, that may be better suited for
large projects. In any event, template-related issues should be addressed early in the
development process.

2.3.5 Names in Header Files

A name declared at file scope in a header file has the potential to collide with any file-
scope name in any file in the entire system. Even names with internal linkage
declared at file scope in a . c file are not safe from file-scope names in a . h file.

Major Desigll RIlle

Only classes, structures, unions, and free operator functions should

be declared at file scope in a . h tile; only classes, structures, unions,
and inline (member or free operator) functions should be defined at
tile scope in a . h file.

The only things we expect to find at file scope in a header file are class declarations,
class definitions, free operator declarations, and in line function definitions. Nesting
78 Ground Rules Chapter 2

all other constructs within class scope eliminates most of the trouble associated with
name collisions.

To help illustrate this rule, an otherwise meaningless header file containing several
constructs is provided with commentary in Figure 2-4. Note that a static instance of
user-defined type is a special case, which is discussed in Section 7.8.1.3. For now,
avoidance of these static user-defined objects in . h files may be treated as a guideline
and not a rule.

II driver.h II fine: comment

#ifndef INCLUDED DRIVER II fine: internal include guard
#define INCLUDED_DRIVER II fine: (see Section 2 .4)
#ifndef INCLUDED NIFTY II fine: redundant include guard
#include "nifty.h" II fine: Cpp include directive
#endif II fine: (see Section 2.5)
:l~oef~i~'~i:~I~I~~1i~'mUtWT41'-~'j··"'·'I·,'• •:!.~.' '.~,.,~•. ,i,.~ ;~:~!I~;!;1;1±:~!'i·l~il!iJ'~ri]J~[j1i,tffi~~iffi~:~jil:;iiiT i;ml';,:[liI-I!~11Ii;;I,'iIM9
•.• •'·#fa·.~'• -f.i• • Q:e • '·• ·iJM'~,i~!.,.~• ·~.·• ·~• .• '· • •(. ',(" i·~• ,~.[·I .·"I·.!·.•~-!:~~;f~l!,t,,~;i~_'~ijf;!~~~!!ji
"I.·'•

class ostream; II fine: class declaration

struct Driverlnit; II fine: class declaration
union Uaw; II fine: class declaration
x.t errlal···• · • ·OaEa···
............. ".:": ::":: .. :. . . . . .

ii~i~tern jnt:glQ6~lVa ria b le; '. \ ii . C,

"

statf¢iilt-tileScOpeVa r i.·ahl te
i n rn~l·d~t~·
Cbtrst i ntBUFFERS lZ E = 2 .. constdata .defi ni ttoh><··
:~hlJ m Boo 1e ahl.ZER
!~'yp~d efl 0 n 9
0, 0) ~Nj~E',:.' ,J}';;, • ti,:!itil:l !~:i.il,i:l i l<ilj8l1 •. i:~~
Big I n t ; ' "
:.i.: • • • • • • .•·.• i.:.·.: • • :••·• • :.

class Driver {
enum Color { RED, GREEN}; II fine: enumeration in class scope
typedef int (Driver::*PMF)(); II fine: typedef in class scope
static int s_count; II fine: static member declaration
int d_size; II fine: member data definition

private:
struct Pnt {
short int d_x, d-y;
Pnt(int x, int y)
: d_x ( x), d-y ( y) {}
}; II fine: private struct definition
friend DriverInit; II fine: friend declaration
Section 2.3.5 Names in Header Files 79

public:
int static roundCdouble d); II fine: static member
II function declaration
void setSizeCint size): II fine: member function declaration
int cmp(const Driver&) canst; II fine: const member
II function declaration
}; II fine: class definition

static classDri verIni t { . :. :... ::.. :: .. :: :::: .. :~ ::::-...... :. .-

I I ...
} driver'Init; 17 s pe c ial c as e . ( see Sec t ion 7. 8 . 1 .3 ) . .

inline
void Driver::setSize(int size)
{
d size = size;
} II fine: inline member
II function definition

ostream& operator«Costream& 0,
canst Driver& d): II fine: free operator
II function declaration

inline
int operator==Cconst Driver& lhs,
canst Driver& rhs)
{
return compare(lhs, rhs) -- 0;
} II fine: free inline operator
II function definition
inline
int Driver::round(double d)
{
return d <0 ? -intCO.5 - d)
intCO.5 + d);
} II fine: inline static member
II function definition

#endif II fine: end of internal include guard

Figure 2-4: Va"rious Constructs at File Scope in a Header File

80 Ground Rules Chapter 2

2.4 Include Guards

If we follow the above recommendation that only class, struct, union, and inline func-
tion definitions appear at file scope in header files, we will still have a problem if the
same header file gets included twice in a single translation unit. This problem could
occur with the simple include graph shown in Figure 2-5.

When component c. 's .c file is compiled, the preprocessor first includes the corre-
sponding header file, c. h, which in tum includes the contents of a. h. Next c. h
includes file b. h, triggering a second inclusion of a . h. If a . h has any definitions at all
(and in C++ it almost surely does) the compiler will complain about multiple defini-
tions.

II C.c
/ I '"
#include "c.h"

C.C

Bad idea: also missing 1/ c.h

redundant include guards
(see Section 2.5)
Hinclude !la.hl!
#include Ilb.hl!
/ I .,. + /-"'-...
Bad idea: missing
include guards

c.h
Includes

Bad idea: missing

include guards
+ // b.h
/linclude "a.h"
//

b.h

II a.h
II
+ Bad idea: missing
include guards

a.h
Figure 2-5: Reconvergent Include Graph Causing Compile-Time Error
Section 2.4 Include Guards 81

lVlajor Desigll Rllle

Place a unique and predictable (internal) include guard around the

contents of each header file.

The time-honored, traditional way of solving this problem is to require an internal

protective wrapper around the contents of each header file. This wrapper ensures that
class and inline function definitions are seen only once in a given translation unit
regardless of the include graph. Note that we are not trying to stop cyclic inclusion
(which is probably a design error); we are trying to stop any repeated inclusion that
might come from reconvergence in an acyclic include graph. A solution to the compil-
ing problem in the previous example is shown in Figure 2-6. Note that we are still
missing redundant (external) include guards (discussed in Section 2.5).

II a.h II b.h II c.h

#ifndef INCLUDED_A #ifndef INCLUDED_B iii fndef INCLUDED_C
#define INCLUDED_A #define INCLUDED_B #define INCLUDED_C

II . . . #include "a.h" #include "a.hl!

II . . . /linclude "b.h"
II ...
1fendf Ilendf #endf

a.h b.h c.h

Figure 2-6: Accommodating Repeated Inclusion Using Include Guards

For example, when a. h is included in a translation unit, the preprocessor will first
check to see if the preprocessor symbol INC LU0 ED_A is defined. If not, the guard sym-
bol INCLUDED_A will be defined once and for all (for this translation unit), and then
82 Ground Rules Chapter 2

preprocessing will proceed by reading the definitions contained within the rest of the
header file. The second (and any subsequent) time this header file is included, the
contents inside the preprocessor 1f i f nde f conditional (i.e., the rest of the file) will be
ignored.

The actual symbol used for the include guard is not important so long as it does not
match any other symbol in the entire system. Since the include guard is tied to a given
header file, and that header file name must be unique in the system, incorporating that
name in the guard symbol can ensure that no two guard symbols are the same.

The preprocessor knows nothing of c++ scoping rules. We must therefore ensure that
the include guard symbols do not match any other symbols at all-even those within
functions defined in a . c file.

Adopting a standard naming convention of prefixing the root name of the header file
in upper case (e.g., STACK) with a globally reserved prefix (e.g., INCLUDED_) ensures
unique and predictable guard names:

II stack.h II iccad_transistor.h
#ifndef INCLUDED STACK #ifndef INCLUDED_ICCAD_TRANSISTOR
#define INCLUDED_STACK #define INCLUDED- ICCAD- TRANSISTOR
I I ... I I ...
#endif #endif

The need for predictability will be made clear in Section 2.5.

2.5 Redundant Include Guards

Practical isn't always pretty, and this is one of those cases. Theoretically, unique inter-
nal include guards are sufficient. With large projects, however, it can be very costly
not to consider a bit further.

A well-designed system consists of layers of abstractions. Where possible, it is desir-

able to create a small number of primitive object types and then compose them to
form objects at higher levels of abstraction. A scientific application might model the
various different kinds of atoms as classes. There are 100 some odd kinds of atoms in
the periodic table. Instances of these relatively few primitive types are composed (via
layering) in various ways and proportions to create all the different types of molecules
in the universe.
Section 2.5 Redundant Include Guards 83

Another example of this type of layered design might be an object-oriented window

system. Suppose we have a collection of N primitive widgets (such as buttons, dials,
slide switches, displays, etc.). We'll name these primitive widget classes WI, W2, ... ,
Wn for short. Each widget, Wi, exists in its own separate translation unit, wi . c, with
its corresponding header file wi . h. New screen types are created by composing the
various types of widget objects. We'll call these M screen classes S 1, S2, ... , Sm,
and each S i lives in its own translation unit with header file s i . h. .

Typically, each screen uses a substantial number of the available widgets. For the pur-
poses of this discussion, assume each screen type uses all (or most) of these primitive
types in a substantive way that prompts the implementors to include all of wI . h, w2 . h,
... , wn . h files in each s i . h file. The header file for a typical screen, S13, is shown in
Figure 2-7.

II sl3.h
#ifndef INCLUDED_513
#define INCLUDED_513

#include "wl.h"
#include "w2.h"
#include "w3.h"
I I ...
#include t'wn.h"
#include <math.h>

class 513 {
WI d_wla;
WI d_wlb;
W2 d_w2;
W3 d_w3;
II
Wn d_wn;
};

#endif

Figure 2·7: Typical Screen Composed of Many Widgets

Do you see a potential problem? Let's continue. Suppose you have developed a good
number of screens, and in some translation unit of your system, c k . c, you need to
include all of the screen headers (say to create them). The include graph for a window
application with N = 5 widgets and M =5 screens is shown in Figure 2-8.
84 Ground Rules Chapter 2

II ck.c .
#include "ck.htt
#include "sl.h ll

#include IIs2.h"
#include "s3.hl'
#include "s4.hl!
#include "s5.hl'

I c1.c I I c2.c I . .. ck.c ... c9.c Imain.cl

(N= 5)

Figure 2-8: Include Graph for One Component in Window System of Size N =5
When the preprocessor sees that c k . c has included s 1 . h, it also includes wI. h
through w5. h. Upon encountering s2. h, each of the widget header files must still be
reopened and reprocessed line by line in its entirety searching for the trailing He nd i f
(only to find that there is nothing else to be done). This redundant preprocessing
occurs with s3. h, 54. h, and again with 55. h. Although this program will compile and
work properly, we had to wait for 25 widget header files to be processed when 5
would have done the job!

Unless care is taken to ensure otherwise, C++ tends to have large, dense include graphs
(much more than C). Although inheritance and layering contribute to this problem, the
underlying cause is often the misguided belief on the part of c++ developers that they
are somehow doing their clients a favor by including in their header file every other
header that a client might need.

Avoiding dense include graphs is part of the topic of Insulation, covered in Chapter 6.
What follows is a practice that will minimize the impact of such reconvergent inclu-
sion, even in a poor design. Note that some development environments are smart
Section 2.5 Redundant Include Guards 85

enough to keep track of previously included header files, but many common environ-
ments are not. If portability is an issue, it is better safe than sorry.

Wir .6i."I,!I.,rcr,~,.;,i.
... ......

Place a redundant (external) include guard around each preprocessor

include directive in every header file.

Place a redundant (external) include guard around each include directive that occurs in
a header file. This technique, applied to a typical screen header file, is shown in Figure
2-9. Processing file s 13. h for the first time will still cause files wI . h, w2 . h, ... , wn . h
to be included. Including another screen, however, will not lead to any redundant
parsing of widget headers.

Notice that the redundant include guard for the math standard library header is differ-
ent from the rest. Although math. h does have its own internal include guard, it proba-
bly doesn't follow our standard. The runtime libraries supplied with different
co~pilers are likely to have different naming conventions for the include guards they
use, and these guard names may not always be consistent. Components supplied by
third-party vendors may use yet another convention. For all components that are not
guaranteed to follow our include-guard naming convention, it will be necessary to add
a line that defines the appropriate include guard symbol after the corresponding
include directive (a~\y'as done for ma t h . h).

Using redundant include guards is admittedly unpleasant. It now takes not one but at
least three lines to include a header in a header file-four lines if the included header
came from outside our sphere of influence. Redundant include guards not only make
headers take longer to write, they make headers harder to read. Using redundant
include guards also requires following a consistent and predictable naming conven-
tion. Is it worth it?

Experience with truly large projects that have dense include graphs shows that the
answer is a resounding YES! Initial builds of projects consisting of several million
lines of C++ source code were taking on the order of a week to compile using a large
86 Ground Rules Chapter 2

network of work stations. Inserting redundant include guards reduced compile time
significantly, with no substantive change to the code.

II s13.h
#ifndef INCLUDED_513
#define INCLUDED_513

#ifndef INCLUDED_WI
#include "wl.hll
lIendif

#ifndef INCLUDED_W2
11 inc 1ude" w2 . h
11'-\,/-

Hendif

1Iifndef INCLUDED_W3
#include "w3.h"
#endif

/ I ...

#ifndef INCLUDED_WN
Hinclude "wn.h"
lIendif

#ifndef INCLUDED_MATH
#include <math.h>
#define INCLUDED_MATH II extra line
#endif

class 513 {
WI d_wla;
WI d_wlb;
W2 d_w2;
W3 d_w3;
I I ,.,
Wn d_wn;
};

#endif

Figure 2-9: Typical Screen Component with Redundant Include Guards

What we have just discussed is typically not an issue for a small or even a medium~"'"
size system. But what would happen if we were dealing with systems that contained;
the equivalent of hundreds of primitive widgets with hundreds of primitive screens?
To provide quantitative information demonstrating the benefits of using redundant
include guards, I tried the following experiment.
Section 2.5 Redundant Include Guards 87

I let N be number of widgets as well as the number of screens. I then generated sub-
systems and measured the compile time (which is dominated by the C preprocessor
time) for a single translation unit, including all of the screen header files with and
without redundant include guards. I tried the experiment with header files having 10
lines each and again with header files of 100 lines each. I defined the speedup factor
to be the compilation time without redundant include guards divided by the corre-
sponding compilation time with redundant include guards added. The results are
shown in Figure 2-10.

10 lineslheader 100 lineslheader

CPU seconds CPU seconds
Speedup Speedup
N Without With Factor Without With Factor

1 0.2 0.2 1.00 0.2 0.2 1.00

2 0.2 0.2 1.00 0.2 0.2 1.00
4 0.3 0.3 1.00 0.4 0.3 1.33
8 0.5 0.3 1.67 0.7 0.4 1.75
16 0.7 0.4 1.75 1.7 0.5 3.40
32 1.5 0.5 3.00 5.8 0.9 6.44
64 5.8 1.1 5.27 22.1 2.0 11.05
128 25.9 3.5 7.40 89.5 5.2 17.21
256 126.5 13.6 9.30 376.5 17.1 22.02
512 702.3 61.6 11.40 1697.4 68.6 24.74
1024 4378.5 306.6 14.28 8303.8 330.6 25.12

Figure 2-10: Preprocessor Times with/without Redundant Include Guards

For systems with fewer than eight widgets and eight screens, the speed-up is either
non-existent or minimal, but given that the total compile time was less than 1 CPU
second, it hardly matters.

Header files in C++ are seldom only 10 lines long; 100 lines is still small but more
typical. For systems with 32 widgets, the time spent in the C preprocessor compiling
each client component on my machine can be reduced by a factor of more than 6
(from 5.8 to 0.9 CPU seconds). For systems with 64 widgets, the speedup is a factor of
over II! Redundant include guards are ugly, but do no real harm. Not using redundant
guards runs the risk of quadratic (i.e., O(N2)) behavior at compile time.
88 Ground Rules Chapter 2

Note that redundant guards are not necessary in . c files. Short of deliberately duplicating
=/Ii n elude directives in the. c file, the (pathological) worst-case behavior, 2N remains
linear (i.e., O(N» with respect to the number of distinct . h files, N.

The data in this section reflects CFRONT running on Unix-based workstations. Other
development environments may have somewhat different characteristics. In Chapter 6
we will see that ne~ting =/Ii ncl ude directives in header files is not only undesirable but
often unnecessary. The ugliness of the redundant include guards, if nothing else,
reminds us that we want to avoid placing #i ncl ude directives in header files when-
ever it makes sense to do so.

2.6 Documentation

The examples in this book do not set a good example for what are sufficient comments
for production code (otherwise this would be three books, not one). But comments,
especially in the interface, are an essential part of the development process.

Guideline
Document the interfaces so that they are usable by others; have at
least one other developer review each interface.

To see why it is valuable to have another developer review your interface, try to put
yourself in the position of a client or a test engineer trying to understand your class.
You know very well how to use your interface-after all, you designed it! The terse
names you supplied as member functions are "obvious" and "self-explanatory." But
unless you have taken the time to have someone else review your interface and docu-
mentation, chances are that there is significant room for improvement-particularly in
its usability.

A big part of usability is being able to pick up an unfamiliar header and just start
using it. In practice, header file comments are often the only documentation (or at
least the only up-to-date documentation) that exists for an interface. If clients are
forced to peek at the implementation in order to figure out how to use your compo-
nent, then it is not documented properly.
section 2.6 Documentation 89

Guideline
Explicitly state conditions under which behavior is undefined.

Another important aspect of documentation is explicitly identifying conditions under

which behavior is not defined. Consider the following declaration:

struct MathUtil {
I I ...
static int fact(int n);
II Returns the product of consecutive integers between 1 and n.
};

What do you think about the comment for function fact? We might guess that fact is
supposed to be the common mathematical functionJactorial (n!), and that fact (0) is
actually 1 and not 1 • 0 = 0 or undefined. However, that is not what the comment says.
What the comment fails to say is what is supposed to happen when n is non-positive!

A factorial is not defined for negative integral values. It may be that our particular
implementation returns 0 in these cases. What fact ( n) returns when the value of n is
negative is an artifice of the implementation and not part of the specification; clients
should be told explicitly not to rely on this behavior. Another implementation replac-
ing this one could easily provide different behavior for negative values of n (including
causing your program to crash).

Unless explicitly stated in our comments, clients and test engineers will, in general,
have no way to distinguish between what is intended or required behavior and what is
simply coincidental behavior resulting from the particular implementation choice. A
better, more usable interface is presented below:

struct MathUtil {
I I ...
static int factorial (int n);
II Returns the product of consecutive integers between 1 and n
II for positive n. If n is 0, 1 is returned.
II Note that the behavior is not defined for negative values
II of n nor for results that are too large to fit in an into
};
90 Ground Rules Chapter 2

Failing to specify explicitly the conditions under which behavior is undefined

inadvertently commits the software to support irrelevant behavior that could affect
performance or limit implementation choice. If a test engineer is not on the ball, you
may find irrelevant behavior produced by your implementation choice inexorably cast
in stone by a suite of regression tests that explicitly test for that behavior. Even worse,
clients, through improper (unintended) use, may come to depend on this coincidental
behavior. ,-
/
;'
/

The use of assert statements can help to document the assumptions

you make when implementing your code.

Error checking throughout every level of a system in order to detect logic errors can
become expensive, especially for large systems. Good documentation can be a viable
alternative to writing excessive code. For example, some software developers feel that
it is necessary to handle every pointer that comes into a function, even if that pointer
is null. If this function is part of a widely used interface, favoring robustness might
well prove to be a good decision. Alternatively, it can be sufficient to make it clear to
clients that passing a null pointer will result in undefined behavior, backing that up
with an assert statement at the beginning of the function implementation:

II stdio.c
#include <stdio.h>
#include <assert.h> ...
1* ... *I
int printf(const char *format ... )
{
assert(format);
1*
*1
}

The effective use of both documentation and assert statements can lead to lighter-
weight code that is still quite usable. If someone misuses the function, it is their own
fault-and they'll find out about it soon enough!
Section 2.7 Identifier-Naming Conventions 91

It would be laudable if every developer always made it clear when, for example, a
pointer argument to functions cannot be null. Responsible cl~ents, however, should
not assume that a pointer argument can be null unless the resulting behavior is
explicitly stated.

2.7 Identifier-Naming Conventions

Distinguishing data member, type, and constant names from other identifier names in
a consistent and objectively verifiable way can be a significant advantage when main-
taining a large system. Section 1.4.1 presented a collection of naming conventions
that we tersely punctuate here with three design rules and two guidelines.

The practice of lexigraphically identifying class data members can be stated

concisely, and its value transcends issues of me~e style. This practice is therefore pre-
sented as a design rule.

Use a consistent method (such as a d_ prefix) to highlight class data

members.

You may also elect to use s_ to distinguish static from instance data. The above prac-
tice is a minor design rule because clients will never have to deal with this issue
(since, according to Section 2.2, data members should always be private).

Use a consistent method (such as an uppercase first letter) to distin-

guish type names.

The above practice is presented as a rule and not a guideline because it is a widely
accepted and objectively verified standard that improves readability in general,
92 Ground Rules Chapter 2

making interfaces easier to understand and code easier to maintain. It is a minor rule
because an isolated lapse is not the end of the world.

Use a consistent method (such as all uppercase with underscore) to

identify immutable values such as enumerators, canst data, and pre-
processor constants.

The above practice helps to distinguish constant (and therefore "stateless") variables
from both local variables and member (state) variables. It is presented as a design rule
and not a guideline because it helps to improve maintainability, it is objectively verifi-
able, and it requires no exceptions.

Guideline ...., . ./:

Be consistent about identifier names; use either uppercase or under-

score but not both to delimit words in identifiers.

The above practice is also objectively verifiable, but not everyone can be convinced o(
its virtue, and it is largely a matter of style. Its utility is in making identifier names
somewhat easier to remember and in exhibiting a more professional image to most
customers. It is presented here as a guideline (particularly for the interface), but toler-
ates some degree of individuality in the implementation. (In this book we have'
adopted the uppercase standard.)

Guideline
Be consistent about names used in the same way; in particular adopt
consistent method names and operators for recurring design patterns
such as iteration.
Section 2.8 Summary 93

Attaining consistency across the interface of a large system can enhance usability and
can also be surprisingly difficult to accomplish. Empowering a group of top-notch
developers to act as "Interface Engineers" has proven effective in achieving consis-
tency across development groups in large projects. Container classes, along with their
iterators, also lend themselves to template implementations (see Section 10.4) that can
be effective at enforcing consistency across otherwise unrelated objects.

2.8 Summary

C++ is a large language, giving way to an even larger design space. In this chapter we
have described a modest set of fundamental design rules and guidelines that have
proven themselves to be useful in practice.

Major design rules are presumed never to be violated. Even infrequent violations
could compromise the integrity of a large system. Throughout this text, we will
assume that all major design rules have been followed consistently.

Minor design rules are also presumed t~'be followed but perhaps not with draconian
adherence. Deviating from a minor rule in isolated instances is unlikely to have a
severe global impact.

Guidelines are presented as rules of thumb, and should be followed unless there is a
compelling engineering reason to do otherwise.

Exposing the member data of a class to its clients violates encapsulation. Providing
non-private access to member data implies that local changes in representation may
force clients to rework their code. Furthermore, by allowing writable access to data
members, there is no way to prevent accidental misuse from leaving data in an incon-
sistent state. Protected member data is like public member data in that there is no limit
to the number of clients that might be affected by a change to that data.

Global variables pollute the global name space and warp the physical structure of a
design in ways that can make independent testing and selective reuse virtually impos-
sible. There is no need to use global variables in new C++ projects. We can systemat-
ically eliminate global variables by placing them in class scope as private static
members, and then provide public static function members to access them. Excessive
dependency on such modules, however, is a symptom of a poor design.
94 Ground Rules Chapter 2

Free functions, particularly those that do not operate on any user-defined type, are
likely candidates for collision with other functions during integrations. Nesting such
functions in class scope as static members all but eliminates the danger of collision.

Enumerations, typedefs, and constant data also threaten the global name space. By
nesting enumerations within class scope, any ambiguity can be resolved via scope res-
olution. A typedef at file scope can look suspiciously like a class, and be surprisingly
difficult to find in a large project. By nesting typedefs in class scope, they become rel-
atively easy to track down. An integral constant defined in a header file is often best
expressed by an enumerator in class scope. Other types of constants can be scoped by
making them static const members of some class.

Preprocessor macros are difficult to understand for both human beings and machines.
Since macros are not part of the C++ language, they are irreverent of scope, and, if
placed in a header file, they can collide with any identifier in any file in the system.
Consequently macros should not appear in header files except as include guards.

All things considered, we will avoid introducing anything into file scope in a header
file other than classes, structures, unions, and free operators. We will, of course, allow
inline member function definitions in headers.

Including a definition twice results in a compile-time error. Since most C++ header
files contain definitions, it is essential that we protect against the possibility of a
reconvergent include graph. Wrapping the definitions inside a header with internal
include guards ensures that the contents of each header will be incorporated at most
once in any translation unit.

Redundant (external) include guards, although not strictly necessary, ensure that we
avoid potentially quadratic behavior at compile time. By wrapping include directives
in header files with redundant guards, we ensure having to open a header file at most
twice per translation unit.

Good documentation is an essential part of development. A lack of documentation

degrades usability. An important part of documentation involves stating what is
undefined; otherwise clients may come to depend on coincidental behavior resulting
solely from the particular implementation choice.
Section 2.8 Summary 9S

Not all code must be robust. Redundant, runtime program-error checking at every
level of the system can have an unacceptable impact on performance. A combina-
tion of documentation and assertions can serve the same purpose, but with superior
runtime performance in the final product.

Finally, providing a consistent set of naming conventions to distinguish data

members, types, and constants can improve readability across development groups.
We suggested using a d_ prefix for data members (5_ if static); using an uppercase
first letter to denote a type and a lowercase one to denote a variable or function; using
all uppercase (including underscore) to denote enumerators, con 5 t data, and prepro-
cessor constants; and using an uppercase first letter to delimit words in multi-word
identifiers. We also recommended using consistent names for recurring design patterns
such as iterators.
 PART II:
P Y I AL DE
N EPT

Developing a large-scale software system in c++ requires more than just a sound
understanding of logical design issues. Logical entities, such as classes and functions,
are like the flesh and skin of a system. The logical entities that make up large C++
systems are distributed across many physical entities, such as files and directories.
The physical architecture is the skeleton of the system-if it is malformed, there is no
cosmetic remedy for alleviating its unpleasant symptoms.

The quality of the physical design of a large system will dictate the cost of its mainte-
nance and the potential it has for the independent reuse of its subsystems. Effective
design requires a thorough grasp of physical design concepts that although closely
tied to many logical design issues include a dimension with which even expert profes-
sional software developers may have little or no experience. Part II of this book pre-
sents a thorough introduction to the fundamental concepts of good physical design.

Chapter 3 introduces the component as the fundamental unit of design. Several

physical design rules are presented to ensure that all our designs have certain impor-
tant desirable properties. The many logical design relationships (e.g., IsA, HasA,
Uses) collapse into a single physical relationship: DependsOn. We see how our logi-
cal design decisions can potentially affect physical dependency. We also see how to
extract physical dependencies efficiently from a collection of existing components.
98 Physical Design Concepts Part II

Chapter 4 describes the importance of physical hierarchy (i.e., layering) with respect to
development, maintenance, and testing. In this chapter we explore how to characterize
individual components, subsystems, and entire systems in terms of their physical depen-
dencies. We see how to exploit the hierarchical structure of sound physical designs to
achieve higher reliability at lower cost through isolation, incremental, and hierarchical
testing. We also measure how the physical dependencies in a system contribute to the
cost of maintenance and regression testing in terms of link time and disk space.

Chapter 5 explores many common causes of excessive link-time dependencies. This

chapter catalogs several techniques and transformations for reducing the link-time
dependencies within a system-a process referred to in this book as levelization. We
use many examples taken from various applications to illustrate these techniques.

Chapter 6 addresses the maintenance cost associated with excessive compile-time

coupling. Several common language constructs that force clients to depend on
encapsulated implementation details are identified. Techniques for mitigating or elim-
inating compile-time dependencies on individual details as well as wholesale tech-
niques for distancing clients from the implementation are presented-a process
referred to in this book as insulation. Finally, the runtime cost associated with insula-
tion is characterized to identify situations under which insulation is not appropriate.

Chapter 7 extends the concept of levelization to very large systems. Additional physical
structure beyond that of individual components is needed to support the complex
functionality of such systems. Packages represent a physically cohesive collection of
cooperating components and provide a higher level of physical abstraction than can be
achieved with components alone. In this chapter we revisit the concepts of levelization
and insulation in the context of packages as a whole. We also touch on issues pertaining
to the process of developing and releasing stable snapshots of a very large system.
Finally, we discuss the role of rna i n ( ) in object-oriented systems and the relative advan-
tages of various strategies for initialization.
 Components

This chapter introduces the notion of physical ,design in contrast to the more popular
topic of logical design. The component is presented as the fundamental unit of design.
Next we explore a small collection of physical rules that ensure important desirable
properties in large designs. We then discuss the DependsOn relation among compo-
nents and see how to infer this relation from abstract logical relationships at design
time. We also see how to track physical dependencies efficiently by examining the
#i nc 1 ude graph among components. Finally, we explore the subtle physical implica-
tions of granting friendship both inside and outside components.

3.1 Components versus Classes

Logical design emphasizes the interaction of the classes and functions defined within
a system. From a purely logical point of view, a design can be thought of as a sea of
classes and functions where no physical partitions exist-every class and free
function resides in a single seamless space. Interactive object-oriented languages such
as Smalltalk and CLOS with their rich, runtime environments geared toward a single
developer have no doubt helped to foster this monolithic perspective.

Logical desigp., however, looks at only one side of the design process. Logical design
does not take into account physical entities such as files and libraries. Compile-time
coupling, link-time dependency, and independent reuse are simply not addressed by
logical design. For example, whether or not a function is declared i n 1 i n e does not
affect what it does, but can greatly affect readily measurable characteristics such as
runtime, compile time, link time, and executable size. Without considering the physical
100 Components Chapter 3

view of a design, it is not possible to consider the organizational issues that become
important when developing very large systems.

Logical design addresses only architectural issues; physical design

addresses organizational issues.

Physical design focuses on the physical entities in the system and how they are
interrelated. In most conventional C++ programming environments, the source code
for every logical entity in the system must reside in a physical entity, commonly
referred to as aftle. Ultimately, the physical structure of every C++ program can be
described as a collection of files. Some of these files will be header (. h) files and
some of them will be implementation files ( . c) files. For small programs, this descrip-
tion is sufficient. For larger programs, we need to impose additional structure in order
to create maintainable, testable, and reusable subsystems.

DEFINITION: A component is the smallest unit of physical design.

A component is not a class and vice versa. 1 Conceptually, a component embodies a

subset of the logical design that makes sense to exist as an independent, cohesive unit.
Classes, functions, enumerations, and so on are the logical entities that make up these
components. In particular, every class definition resides in exactly one component.

Structurally, a component is an indivisible, physical unit, none of whose parts can be

used independently of the others. The physical form of a component is standard and
independent of its content. A component consists of exactly one header (. h) file and
one implementation ( . c) file. 2

1 The notion of a component is presented in stroustrup, Section 12.3, pp. 422-425. In this chapter,
we expand on that discussion by introducing physical design concepts that make the definition of a
component in C++ concrete.
2 We will ignore extraordinary circumstances that might justify a component having more than a
single . h or . c file.
Section 3.1 Components versus Classes 101

A component will typically define one or more closely related classes and any free
operators deemed appropriate for the abstraction it supports. Basic types such as
Point, String, and Biglnt will each be implemented in a component containing a
single class (Figure 3-1 a). Container classes such as In tSet, Sta c k, and Lis twill
typically be implemented in a component containing (at least) the principle class and
its iterator (Figure 3-1 b). More complex abstractions involving multiple types such as
Graph can embody several classes in a single component (see Figure 3-lc). Finally,
classes that provide a wrapper for an entire subsystem (see Section 5.10) may form a
thin encapsulating layer consisting of one or more principle classes and many iterators
(Figure 3.1d).

Each of the components in Figure 3-1 (like every other component) has a physical as
well as a logical view. The physical view consists of the . h file and the . c file, with
the . h file included as the first substantive line of the . c file. The physical implemen-
tation of a component always depends on its interface at compile time. This internal
physical coupling contributes to the need to treat these two files as a single physical
entity.
102 Components Chapter 3

Logical View Physical View

point point

intset.h intset.c

intset intset

graph.h graph.c

graph graph

(d)~~~~~~~~~~

simulator.h ~~~~ simulator.c

simulator simulator
Figure 3-1: Logical versus Physical View of Several Components
Section 3.1 Components versus Classes 103

A component is the appropriate fundamental unit of design.

A component (and not a class) is the appropriate fundamental unit of both logical and
physical design for at least three reasons:

1. A component bundles a manageable amount of cohesive functionality

that often spans several logical entities (e.g., classes and free operators)
into a single physical unit.

2. Not only does a component capture an entire abstraction as a single

entity, but it also allows for consideration of physical issues not addressed
by class-level design.

3. An appropriately designed component (being a physical entity unlike a

class) can be lifted as a single unit from one system and reused effectively
in another system without having to rewrite any code. Throughout this
book, the need to consider physical as well as logical design issues will
become increasingly evident.

As a concrete example, Figure 3-2 shows the header file for a stack component con-
taining two classes defined at file scope, namely, St a c k and St a c kIt e r. We can also
see that there are two free (i.e., not member) operator functions implementing == and
!= between two Stack objects. Peeking at the implementation, we would discover
that operator== uses Stacklter, and that operator!= is implemented in terms of
operator==. The complete set of logical entities at file scope in component stack is
pictured in Figure 3-3a. The physical entitles (s t a c k . hand s t a c k . c) along with their
canonical physical relationship are depicted in Figure 3-3b.
104 Components Chapter 3

II stack.h
#ifndef INCLUDED_STACK
#define INCLUDED_STACK
c1 ass StackIter;
class Stack {
int *d_stack_p; II pointer to array of int
int d_sp; II stack pointer (index)
int d_size; II size of current array of in!
friend StackIter; II (no comment needed)

public:
II CREATORS
Stack(); II create an empty Stack
Stack(const Stack& stack); II (no comment needed)
""'Stack(); II (no comment needed)
II MANIPULATORS
Stack& operator=(const Stack& stack); II copy Stack from Stack
void pushCint value); II push integer onto this Stac~
int pope); II pop integer off this Stack
II undefined if Stack empty .
II ACCESSORS
int isEmpty() const; II 1 if empty else a
i nt top () c,o ns t ; II integer on top of this Stack
, .
}, . II undefined if Stack empty
int operator==(const Stack& lhs, const Stack& rhs);
II 1 if two stacks contain identical values else 0
int operator!=Cconst Stack& lhs, const Stack& rhs):
II 1 if two stacks do not contain identical values else 0
class Stacklter { II iter order: top to bottom
int *d_stack_p; II points to orig. stack array
int d_sp; II local stack pOinter (index)
StacklterCconst Stacklter&); II not implemented
Stacklter& operator=(const StackIter&); II not implemented

public:
II CREATORS
Stacklter(const Stack& stack); II initialize to top of Stack
-StacklterC); II (no comment needed)
II MANIPULATORS
void operator++(); II advance state of iteration
II undefined if done
II. ACCESSORS
operator canst void *() const; II non-zero if not done else 0
int operatorC)() const; II value of current integer
}; II undefined if done
#endif
Figure 3-2: Header File stack. h for a stack Component
Section 3.1 Components versus Classes 105

.. .

..... ·operator=/) ......

stack.h stack.c

stack stack
(a) Logical View (b) Physical View

Figure 3-3: Two Views of a s t ac k Component

We have chosen a simple stack to ensure that the application functionality does not
obscure the points we want to illustrate. In this example, almost every member is
commented (which is a bare minimum for production code). A stack is a kind of con-
tainer. Access to other than the top element of a stack is not nonnally thought of as
part of a stack abstraction. We have provided the iterator to make the functionality
defined in this stack component more generally extensible by clients, while preserv-
ing encapsulation (see Section 1.5). We make no mention of a maximum stack size
because a stack abstraction has no maximum size. Providing functionality such as
i s Full or a return status that exposes artificial limitations imposed by a substandard
implementation not only violates the abstraction but also complicates its use. Such
unexpected, implementation-based limitations are better treated as exceptions. Some-
times, however, we will allow a client to "help" an object to anticipate future events,
potentially improving performance. In order to avoi~ exposing a particular implemen-
tation choice, such "help"-like regi ster in C or i nl i ne in c++ should be only a
hint and have no programmatically detectable effect (see Section 10.3.1).

DEFINITION: The logical interface of a component is that which is

programmatically accessible or detectable by a client.
106 Components Chapter 3

The logical interface of a component is the set of types and functionality defined in
the header file that are programmatically accessible by clients of that component.
Private implementation details that for organizational reasons reside in the . h file are
encapsulated and not considered part of the logical interface.

DEFINITION: A type is Used-In-The-Interface of a component if the

type is used in the public (or protected) interface of any class defined,
or any free (operator) function declared at file scope in the . h file for
that component.

In the same sense that the public interface of a class consists of the union of the inter-
faces of the public members of that class (Section 1.6.2), the "public" interface of a
component consists of the collection of all public member functions, typedefs, enu-
merations, and free (operator) functions declared in the component's. h file.

For example, the public member functions of both St a c k and St a c kIt e r contribute to
the logical interface of component stack. The free operator function

aperator==(const Stack&, canst Stack&)

is not a member of St a c k and therefore is not considered as part of the logical inter-
face of class Stack. Nonetheless, this operator does extend the set of programmati-
cally accessible functions defined in component stack and therefore does extend the
component's logical interface. The somewhat subtle issues surrounding friendship are
discussed in Section 3.6.

Figure 3-4 shows a tiny driver program, s t a c k . t . C, that creates a St a c k object,

pushes a few integers onto it, and then prints out its contents in order, from top to bot-
tom. The driver can access the logical interface of the stack component, but not its
organizational structure. However, there is more information present in the s ta c k
component's. h file than is programmatically accessible.
Section 3.1 Components versus Classes 107

II stack.t.e
#include "stack.h"
#include <iostream.h>

rna i n ( )
{
Stack stack;
stack.push(III);
stack.push(222);
stack.push(333);

for (StackIter it(stack); it; ++it) {

cout « itC) « endl;
}
};

II Output:
II 333
II 222
II 111

Figure 3-4: Driver s t a c k . t . c for Component s t a c k

DEFINITION: The physical interface of a component is everything in

its header file.

The physical inteiface of a component consists of all of the information available in

the. h file (regardless of access privilege). The more information contained within its
. h file, the more likely that changes to a component's implementation will affect its
clients and cause them to recompile.

Any programmer can tell merely by looking at s t a c k . h that this is an array-based

stack (it is not implemented, for example, as a linked list). For a compiler to do its job,
it must look at s t ac k . h in its entirety. The compiler must consider even private infor-
mation (e.g., d_stack_p) that, from a logical point of view, is strictly an implementa-
tion detail. A consequence of this physical exposure is that an implementation change
that leaves the logical view of the stack component's interface untouched can still·
make it mandatory for all clients that include s t a c k . h to recompile.

As programmers, we observe that none of the functions in s t a c k . h have been

declared i n1 i ne. Modifying the bodies of any of the functions in this component
108 Components Chapter 3

therefore will not alter the physical interface, thus forcing clients to recompile. The
downside is that for a lightweight object such as St a c k, removing inline functions
could result in an order-of-magnitude loss in runtime performance (see Section 6.6.1).

DEFINITION: A type is Used-In-The-Implementation of a compo-

nent if that type is referred to by name anywhere in the component.

From a logical point of view, what is and is not used in the implementation of a com-
ponent is an encapsulated detail and unimportant. From a physical point of view, such
usage can imply physical dependencies on other components. It is these physical
dependencies that will affect maintainability and reusability in large systems.

Good design requires that the developer understand the issues involved in both logical
and physical design. Logical design is the natural place to start. We must consider
what logical entities either naturally belong together or are sufficiently interdependent
that they cannot reasonably be separated. We must also consider how much of the
implementation detail we want to expose in the physical interface. Furthermore, we
need to decide on what other components our component will depend, and what impact
changes in these components will have on both our own component and its clients. A
component has not been designed properly until all of these issues have been
addressed.

3.2 Physical Design Rules

This section considers the fundamental rules of physical design. These rules are
necessary if our other practices and techniques are to be effective. It is virtually
impossible to correct a large design that has not followed these practices in essence
from the start.

Major Desigll Rllie

Logical entities declared within a component should not be defined

outside that component.
Section 3.2 Physical Design Rules- 109

It may seem obvious, but this rule should be stated clearly once. For a component to
be reusable it must be reasonably self-contained. A component may have dependen-
cies on other components. However, any logical constructs (apart from class declara-
tions) that a component declares within its own header file-if defined at all-should
be defined entirely within that component.

Figure 3-5 is an example of how not to partition logical entities into physical units.
Class St a c k has been defined in component s t a c k, but its implementation is not con-
fined to the s t a c k component. St ac k: : pus h is defined in set. c, and St ac k: : pop is
defined in ma in. c !

II intset.h II stack.h
#ifndef INCLUDED_INTSET #ifndef INCLUDED STACK
#define INCLUDED INTSET #define INCLUDED STACK
class IntSet { class Stack {
I I ... I I ...
public: public:
II I I ...
II void push(int i);
II int pope);
}; };
#endif 1Iendif
intseth stack.h

II intset.c II stack.c II main.c

#include "intset.h" #include "stack.h" #include "intset.h"
I I ... II #include "stack.h"
Stack: :push(int i) II int Stack::pop()
{ II {
I I ... I I .. . I I ...
} I I .. . }

II I I ... II
•
intset.c stack.c maln.c

Figure 3-5: Illegal Physical Partitioning of Logical Entities

In addition to causing a maintenance nightmare, failing to adhere strictly to the above

design rule can result in the loss of many desirable physical properties of a design (in
particular, the ability to pick up and reuse translation units in other programs). Following
this rule meticulously will improve both the modularity and maintainability of a
project of any size.
110 Components Chapter 3

The root names of the . c file and the . h file that comprise a component
should match exactly.

It is important for maintainability that the root names of a component's files match
exactly. Knowing, for example, that s t a c k . c and s t a c k . h comprise a single compo-
nent not only facilitates manual maintenance but also opens the door to simple object-
oriented design automation tools (see Appendix C).

Unfortunately, some existing object code archivers place relatively low character lim-
its (e.g., 13) on object file names. Hence it is not always possible to have the name of
the component's. c file mirror the name of its principal class. Worse, some operating
systems limit file names to only eight characters (plus a three-character suffix), which
can be a significant burden when developing very large systems.

l\:Jajor Desigll Rlile

The . c file of every component should include its own . h file as the
first substantive line of code.

We must include the . h file of a component in its . c file because the compiler must
see the declaration of a class member before it can compile its definition. This practice
is required by the language and also by many common dependency-analysis tools. The
reason for placing this 11 inc 1u de directive at the top of the file is somewhat subtle.
section 3.2 Physical Design Rules 111

Latent usage errors can be avoided by ensuring that the . hfile of a

component parses by itself-without externally-provided declara-
tions or definitions.

Including the . h file as the very first line of the . c file ensures that no critical piece of
information intrinsic to the physical interface of the. component is missing from the
. h file (or, if there is, that you will find out about it as soon as you try to compile the
. c file).

Consider the following header file for component wi 1dthi ng:

II wildthing.h
#ifndef INCLUDED_WILDTHING
#define INCLUDED WILDTHING

class WildThing {
I I ...
public:
WildThing();
I I ...
};

ostream& aperator«(canst astream& a, canst WildThing& thing);

II Note: uses class astream in the interface

1tendif

Notice that we have overloaded the left-shift operator « <) in the way that is normal
and customary for stream output. Next consider the implementation:

II wildthing.c
#include <iostream.h>
#include "wildthing.h"
I I ...

astream& operator«(const astream& a, canst WildThing& thing)

{
I I ...
}
112 Components Chapter 3

We try to compile the implementation, and it compiles just fine. Next we create a test
file for wi 1 dthi ng:

II wildthing.t.c
#include <iostream.h>
#include "wildthing.h"

int maine)
{
WildThing wild;

II
I I ...

cout « wild « endl;

return 0;
}

File wi 1 d t hi n9 . t . c compiles and links. The program runs perfectly, and we go tell
all our friends that we are done. But there is a bug and a physical bug at that! The fol-
lowing program will not compile. Why?

II product.c
#include "wildthing.h"
#include <iostream.h>

int maine)
{
WildThing wild;

II
I I ...

cout « wild « endl;

return 0;

The problem is that we did not declare class 0 s t rea mbefore we tried to use it in the
interface of opera tor< < that is declared in wi 1dth i ng . h. The order of the #i n elude
directives was reversed in the client code, and now the header itself doesn't parse
because the 0 s t rea midentifier is not yet declared. How do we fix the problem?
Section 3.2 Physical Design Rules 113

When you figure out the bug, the fix is simple: add the declaration "c 1 ass
as t ream;,,3 to wi 1 dt hi ng . h at file scope before the first use of ostrearn:

II wildthing.h
#ifndef INCLUDED_WILDTHING
#define INCLUDED_WILDTHING

class ostream; II was missing before, oops!

class WildThing {
I I ...
public:
WildThing();
I / ...
};

ostream& operator«(const ostream& 0, const WildThing& thing);

#endif

The more important question is How do we prevent the problem? The answer is
equally simple. Always make the . c file of each component include the . h file for that
component before including or declaring anything else. In this way each component
ensures that its own header file is self-sufficient with respect to compilation.

Guideline
Clients should include header files providing required type defini-
tions directly; except for non-private inheritance, avoid relying on
one header file to include another.

Whether or not one header file should include another is a physical, not a logical,
issue. In cases where the header file itself needs a definition in another header file in
order to compile (see Section 6.3.7), it is correct to place the appropriate #i nc 1 ude
directive in that header file (surrounded, of course, by redundant external include
guards as described in Section 2.5).

3 And not the preprocessor directive /I inc 1ude <i os t rea m. h> (as explained in Section 6.3.7).
114 Components Chapter 3

Except for public and protected inheritance, however, the need to include a type's def-
inition rather than forward declare it in the header file is almost always dictated by
encapsulated logical implementation details.

For example, if class My Ty Pe uses class St a c k in its implementation, it may be necessary

to include s t ac k • h in my ty pe . h to ensure that my t y p e • h compiles. If I decide to change
the implementation of MyType to use Lis t instead of Sta c k, I would no longer need the
Hi nc 1ude "s ta c k . h" directive in mytype . h. Any client that depended on mytype • h to
include s t a c k . h would now have to be changed to include s t a c k . h directly.

How we layer one type on another will affect the degree of compile-time coupling.
Incrementally r~ducing compile-time coupling is the topic of Section 6.3. For exam-
ple, whether My Ty Pe HasA (embeds) St ac k or HoldsA (pointer to) St ac k could deter-
mine whether my ty pe . h includes s t a c k . h or simply forward-declares class St a c k
(see Section 6.3.2). If I alter the implementation of MyType so that it now HoldsA
(instead of HasA) Stack, the Hi ncl ude directive may no longer be needed in
mytype. h. If I remove that directive, then clients who depended on how St a c k was
used in the implementation of MyType would also be forced to change. Even if Stack
were used in the logical interface of MyType, there might still be no need for mytype . h
to include stack. h (see Section 6.3.7). It is up to each client that uses Stack substan-
tively to include its definition directly.

Inheritance is an exception because it always implies a compile-time dependency and

is also part of the logical interface of the deriv~d class. Altering the inheritance hierar-
chy in any way that would permit component authors to remove Ifi n c 1 ude directives
from component header files would also change the logical interface, forcing clients
to be revisited regardless of physical issues. It is therefore reasonable for clients to
include only a derived class definition and rely on the derived classts header file to
include the base class definition.

For similar reasons, it would be unwise for a client to rely on the header of some com-
ponent to forward declare a class used only in that component's logical implementation.
Section 3.2 Physical Design Rules 115

lVIajor Desigll Rule

Avoid definitions with external linkage in the . c file of ~ component

that are not declared explicitly in the corresponding . h file.

For analysis, maintenance, and particularly testing, it is important that someone (or
some tool) be able to look at only the physical interface of a component and under-
stand the complete logical interface of that component. Requiring a component to
declare its entire logical interface in its header file serves to improve

1. Usability-by making it possible to fully understand from the interface

alone the entire abstraction a component supports.

2. Reusability-by ensuring that all supported functionality supplied by the

component is equally accessible to all.

3. Maintainability-by avoiding unsupported "backdoor" interfaces that

would violate the abstraction the component supports.

Suppose someone defined an external free function (or vari~ble) in the. c file of com-
ponent foo and failed to declare it as external function (or variable) in foo. h. Another
component, ba r, that happened to link with foo could obtain access to that function
(or variable) by creating the appropriate external declaration locally. This unfortunate
scenario is depicted in Figure 3-6. Note that this example illustrates a poor design (the
kind of example I have tried to avoid presenting in this book).

As the figure shows, the. c file of ba r is dependent on the definitions supplied by the
physical implementation of foo but is independent of foo's physical interface. There
is a "backdoor" usage of foo and an implicit physical dependency of bar upon foo
that cannot be detected easily. Automated dependency generators for makefiles
(mkmf, gmake, etc.) that take into account only the iii ncl ude graph would have no
clue of this subtle dependency. Moreover, to the maintainers of this code there is no
immediate evidence that these two components are coupled. Yet, when we go to reuse
ba r, the link phase will fail because the definition of function f (and global variable
size) will be missing.
116 Components Chapter 3

Bad idea: Free functions and global variables are design-rule violations.

II bar.h II bar.c
#ifndef INCLUDED BAR #include "bar.h"
#define INCLUDED_BAR
I I ... extern int size;
void feint x, int y);

int Bar: :g()

{
size = f(x. y);
#endif }

bar
illegal "backdoor"
physical dependency

II foo.h II foo.c
#ifndef INCLUDED FOD #include "foo.h"
#define INCLUDED_FOD
I I ... int size;
void f(int x, int y)
Note: neither s i zenor f {
is declared in this I I ...
}
file.

lIendif

foo

Figure 3-6: Poor Physical Design Where ba r. c Depends on foo. c Directly

Section 3.2 Physical Design Rules 117

II bar.h II bar.c
#ifndef INCLUDED BAR 4finclude "bar.h"
#define INCLUDED BAR #include "foo.h"
// ...
int Bar::g()
{
size = f(x, Y);
}

4fendif

bar
legal physical dependency

II foo.h II foo.c
#ifndef INCLUDED_FDD #include "foo.hl!
#define INCLUDED_Faa

extern int size; int size;

void f(int x, int y); void f(int x, int y)

{
I / ...
#endif }

foo

Figure 3-7: (Somewhat) Better Physical Design Where ba r. c Depends on foo. h

118 Components CbapterJ

Had the complete interface been specified in f 0 0 . h, the client component, bar, could
simply have included the foo. h file in its own. c file, making the dependency of the
implementation of ba r on the interface of foa explicit. This new and somewhat;
improved implementation is illustrated in Figure 3-7. However, the use of an external
global variable or an external free function is still a violation of the design rules pre-
sented in Section 2.3.1 and 2.3.2, respectively.

Classes defined at file scope entirely within the . c file of a component could easily
violate this rule, since non-inline class member functions and static member data have
external linkage. If we impose the same restrictions on classes defined entirely in a . c
file that the C++ language itself imposes on local class definitions (i.e., classes
defined entirely within a single function),4 we can avoid creating external definitions
and thereby avoid violating this rule.

Though technically a rule violation, defining a class entirely within a . c file is rela-
tively harmless in practice because name mangling will tend to discourage one from
trying to make direct use of the external symbols. The only real danger is that the
external definition may collide with some other identical definition (which would still
be the case if that class were defined in its own separate component). A more compel-
ling reason to avoid defining classes entirely in a . c file might be that it cannot then
be tested directly (see Section 8.4).

Avoiding backdoor usage is critical to good physical design and effective reuse. It is
not enough to put the burden solely on the author of a component. To close all the
loopholes, we must make a reciprocal requirement that no client attempt to make use
of any construct with external linkage via local declarations. Instead, clients are
required to include the . h file of a component in order to access any definitions that
the component provides.

4 ellis, Section 9.8, pp. 188-189.

Section 3.2 Physical Design Rules 119

l\/{ajor Desigll Rllle

Avoid accessing a definition with external linkage in another

component via a local declaration; instead, include the . h file for that
component.

Our reason for following this rule is primarily to make the dependency on external
definitions in other components explicit.

Including the header as opposed to supplying a local function declaration has

advantages for clients as well. Occasionally headers change. How will your local dec-
larations change to reflect these header changes? An incorrectly declared function
with C++ linkage can at least be caught at link time, 5 but incorrect local declarations
of functions from the Standard C Library (with C linkage) could go undetected until
runtime.

For example, the following will compile and link:

II foo.c
#include "foo.h"
extern de" double pow{double, int); II bad idea: local extern declaration

double Foo::func(double x, double ~)

{
return pow(x, y) + pow(y, x);
}

However, we will get incorrect results at runtime because the local ext ern declaration
does not match the actual definition of pow: 6

extern "(" double pow(double, double)

{
1* *1
}

5 SeeType-Safe Linkage in ellis, Section 7.2c, pp. 121-126.

6plauger, Chapter 7, p. 138.
120 Components t.;hapter j

The mismatched declarations will cause the second argument of pow to become
garbled. We can avoid such problems and make the dependency explicit by including
the . h file instead:

II foo.c
Hinclude "foo.hl!
#include <math.h> II pow()

double Foo::func(double x, double y)

{
return pow(x, y) + pow(y, x);
}

By including the header files, inconsistencies with functions having either linkage
characteristic will be caught at compile time, which is eminently preferable to either
link time or runtime.

It is important to mention that class declarations of the form

class QueueLink; II forward declaration of class QueueLink

are an entirely different matter because class definitions have internal linkage. Such
declarations are not only common but desirable, especially where they can eliminate
preprocessor Hi n c 1 ude directives in header files. This use of class declarations is dis-
cussed with respect to link-time dependencies in Section 5.10 and again with respect
to compile-time dependencies in Section 6.4.3.

3.3 The DependsOn Relation

Physical dependencies among the components that make up a system will affect its
development, maintenance, testing, and independent reuse. The logical relations
among classes and free (operator) functions will imply physical dependencies among
the components in which they reside. We can define implementation dependency for
functions loosely by saying that a function depends on a component if that component
is needed in order to compile and link the body of that function. We can define imple-
mentation dependency for classes in a similar way. More generally, we can define pre-
cisely a central and purely physical relation among components.
Section 3.3 The DependsOn Relation 121

DEFINITION: A component y DependsOn a component x if x is

needed in order to compile or link y.

The DependsOn relation is quite different from the relations we have already seen.
IsA and Uses are logical relations because they apply to logical entities, irrespective
of the physical components in which those logical entities reside. DependsOn is a
physical relation because it applies to components as a whole, which are themselves
physical entities.

The notation used to represent the dependency of one physical unit on another is a
(fat) arrow. For example,

implies that component pl ane depends on component wi ng. That is, component
p 1 an e cannot be used (i.e., it cannot be linked into a program or possibly even com-
piled) unless component wi ng is also available.

As has been our convention, logical entities are represented by ellipses, and physical
entities are represented by rectangles. Notice that the arrow used to indicate physical
dependency is drawn between components and not individual classes. The (fat) arrow
notation used to denote physical dependency should never be confused with the arrow
notation used to denote inheritance. An inheritance arrow always runs between two
classes (which are logical entities); a DependsOn arrow connects physical entities
(such as files, components, and packages).

To illustrate the DependsOn relation in action, consider the following skeleton header
file for a string component. By the way, don't try to name your component "string"; it
may not work well in the presence of the standard C library header s t r i n9 . h.
122 Components Chapter 3

II str.h
#ifndef INCLUDED STR
#define INCLUDED_STR

#ifndef INCLUDED_CHARARRAY
#include "chararray.h"
#endif

class String {
CharArray d_array; II HasA
I / ...
public:
I I ...
};

II

#endif

There is just enough information visible for us to see that class St r i n 9 has a data
member of type CharArray. We know from C that if a struct has an instance of a
user-defined type as a data member, it will be necessary to know the size and layout of
that data member even to parse the definition of the s t rue t.

DEFINITION: A component y exhibits a compile-time dependency on

component x if x. h is needed in order to compile y . c. .

More specifically, it is not possible to compile any file that needs the definition of
St r i n9 without first including c h a r a r ray. h. For that reason we are justified in
nesting #i ncl ude "cha ra rray. h" in the header file of component str along with
the concomitant, redundant include guards.
Section 3.3 The DependsOn Relation 123

str.h chararray. h 1«>iN

str.c chararray.c ~i;ulm!fiil

str chararray

Figure 3-8: Indirect Compile-Time Dependency of s t r . c on c ha r a r ray. h

Figure 3-8 illustrates the physical dependency of component str on component

cha ra rray. A component's. c file must always depend on its. h file at compile time.
Since s t r . c will not compile without s t r . h, and s t r . h will not compile without
c h a r a r ray . h, s t r . c has an indirect compile-time dependency on c h a r a r ray . h.
Notice again that the arrow used to indicate the physical dependency is drawn
between two physical entities (in this case, files). A more abstract representation of
physical dependency at the component level is shown in Figure 3-9.

sOn

str chararray

Figure 3-9: Abstract Representation of Component Dependency

124 Components Chapter 3

A component need not be dependent on another at compile time to be dependent on it

at link time. Consider the following implementation for component word and an alternate
implementation of component str:

II word.h II str.h
#ifndef INCLUDED_WORD #ifndef INCLUDED_STR
#define INCLUDED_WORD #define INCLUDED_STR

#ifndef INCLUDED_STR
#include "str.h" class CharArray:
#endif

class Word { class String {

String d_string; II HasA CharArray *d_array_p; II HoldsA
I I ... I I ...
public: public:
Warde); String();
I I ... II
}; };

#endif #endif

II ward.c II str.c
#include "ward.h" #include "str.h"
#include "chararray.hll

I I ... I I ...

Compiling c h a ra r ray. c of course requires c ha r a r ray. h. Both s t r . hand

chararray.h are needed to compile str.c. Finally, both word.h and str.h are
needed to compile w0 rd. c. Notice that c ha r a r ray. h is not needed in order to compile
word. c. There is no compile-time dependency of component word on component
chararray. However, word still exhibits a physical dependency on chararray, which
will become obvious as soon as we try to link word to a test driver.

DEFINITION: A component y exhibits a link-time dependency on

component x if the object file y. a (produced by compiling y. c) con-
tains undefined symbols for which x. a may be called upon either
directly or indirectly to help resolve at link time.
section 3.3 The DependsOn Relation 125

Recall that, except for inline functions, all class member functions and static data mem-
bers in C++ have extemallinkage. For all practical purposes we can say that if a compo-
nent needs to include another component in order to compile, it is going to depend on
that component at link time to resolve undefined symbols at the object-code level.

I
,,"

,',
:', "

A compile-time dependency almost always implies a link-time

dependency.

word.h str.h chararray. h

word.c str.c

word str chararray

word.o str.o chararray.o

Figure 3-10: Link-Time Dependency of word on cha ra rray

As Figure 3-10 shows, word.o depends on external names. defined in str.o. Even if
word.o does not directly use names defined in chararray.o, it does use names
defined in s t r . o. The names used in s t r . 0 to resolve these undefined symbols will
126 Components Chapter 3

probably introduce new undefined symbols whose definitions must be supplied by

c ha r a r r ay . o. Given the above, we come to an interesting and important conclusion.

The DependsOn relation for components is transitive.

For example, assume x, y,and z are components. If x depends on y, and y depends on

Z, then x depends on z. The transitive property of dependency among components
makes no mention of which file in one component is dependent on which file in the
other. Any such file-level dependency is sufficient to produce an implementation
dependency for the components as a whole.

The abstract, component-level dependency diagram for the previous example is

shown in Figure 3-11. The compile-time dependencies of wo rd on s t r and of s t r on
cha ra r ray have produced the indirect (link-time) dependency of wo rd on cha ra r ray.

implied by transiti vi

String
word str chararray

Figure 3-11: Abstract, Component-Level Dependency Diagram

The DependsOn relation is important to physical design because it indicates all the
components required for the functionality supplied by a given component to be main-
tained, tested, and reused. We have just seen how to infer physical dependency from
the source code itself. As we will see in Section 3.4, it is possible to infer physical
dependency directly from abstract logical relationships such as IsA and Uses. Infer-
ring physical dependencies at the design stage will help us to achieve a sound physical
architecture early in the development process.
Section 3.4 Implied Dependency 127

3.4 Implied Dependency

Logical designs imply certain physical characteristics. We would like to be able to

take full advantage of known logical relationships in order to predict the physical
implications of our logical design before it is implemented. Resulting undesirable
physical characteristics will often force us to alter or even entirely rework our logical
designs. In this section we focus on the implications of logical design on physical
dependency, beginning with the Uses relation.

1.
•.
1.· ••.••.•.· •. :.••..•••.. ~i-illill~ . I
..•....••.....•.

A component defining a function will usually have a physical depen-

dency on any component defining a type used by that function.

Unless otherwise stated, we will assume that if a function uses a user-defined type, it
does so in a substantive way. To explain what we mean by substantive, let us assume
for the moment that if a function uses a type in its interface, it will be necessary for
the component defining that function to include the . h file for the component defining
that type.

II two.c II one.h
#include "two.h" #ifndef INCLUDED_ONE
#include "one.h" #define INCLUDED_ONE
I I ... I I ...
int Two::getlnfoCconst One& one) class One {
{ I / ...
return one.infoC); int infoC) const;
} II
II };
II
#endif

Figure 3-12: The Uses Relation Often Implies a Compile-Time Dependency

Figure 3-12 illustrates our assumption that if function Two: : getlnfo uses class One in
its interface, then it likely does something with One in its implementation that would
require having seen One's definition. In this example, Two: :getlnfo invokes the
128 Components Chapter 3

con s t member function i n f 0 of class 0 ne, which requires the compiler to see the
definition of One in order to compile two. c.

The assumption that the Uses relation implies a compile-time dependency is too
strong. However, this assumption predicts physical implementation dependencies
fairly accurately. It is not necessary for the Uses relation to cause a compile-time
dependency in order to induce an indirect physical dependency. To see how an indi-
rect link-time dependency can occur, consider adding another component, th ree, and
two more files, two. hand three. c, to those of the previous example.

II three.c II two.h
#include "three.h" #ifndef INCLUDED_TWO
#include "two.h" #define INCLUDED_TWO
I I ... class One;
int Three::x2info(const One& one) I I ...
{ class Two {
return 2 * Two::getlnfo(one); I I ...
} public:
II static int getInfo(const One& one);
I I ...
};
II
1Iendif

Figure 3-13: Uses Relation Almost Always Implies a Link-Time Dependency

As shown in Figure 3-13, three.c defines a member function, x2info, which uses
class One in its interface. However, the argument to x2i nfo is passed by reference and
x2 i n fa makes no substantive use of One '8 definition before passing its argument off to
Two's static member function getlnfo, which also accepts a One object by reference.
The x2i nfo function in component three treats class One opaquely and does not
know anything about One other than that it is a c 1 ass, s t ruct, or un ion.

Suppose that no other function in class Th ree uses One (substantively), and also that
there is no other compile-time dependency of component three on component one.
That is, th ree. h and two. h alone are sufficient to compile th ree. c, even though One
is used in the interface of three. But function x2i nfo does depend on One indirectly.
If we try to test th ree, we will not be able to link until we have written and compiled
two. c. To do that, two. c will have to include one. h.
section 3.4 Implied Dependency 129

As Figure 3-14 illustrates, implementation dependency brought on by using an object

is transitive. That is, if Three uses Two and Two uses One, then the component that
defines Three (almost always) DependsOn the component that defines One. In this
case, function x2i nfo in component three used One (trivially) but also used function
getlnfo defined in component two. Function getlnfo also uses One in its interface,
but this time get I n f 0 uses 0 n e substantively in its implementation.

U ses-In -Interface

three two

ends On
(Implied Indirect Link-Time Dependency)

Figure 3-14: Logical Uses Relation Implying Component Dependency

It is possible to use another object without inducing either a compile-time or link-time

dependency on that object. In practice, such limited usage sometimes occurs by design,
but almost never by chance. We will explore this design technique in Section 5.4.

A component defining a class that IsA or RasA user-defined type

always has a compile-time dependency on the component defining
that type.

Certain logical relationships have strong physical implications. For example, deriving
from a type (IsA) or embedding an instance of a type (RasA) always implies that a class
will depend on that type at compile time. In fact, these logical relations imply a com-
pile-time dependency not only for, the class itself, but also for any client of the class.

Figure 3-15 illustrates the physical implications of IsA and RasA for the example in
Figure 3-11. This time Wo rd is reimplemented as a kind of St ring, and St ring has a
130 Components Chapter 3

CharArray data member. 7 The definitions for both String and CharArray must be
available in order for W0 rd. c to compile. Moreover, every client of W0 r d will also
require the definitions both St r i n g and Ch a r Ar ray in order to compile. These same
strong physical implications hold for private derivation and for inline functions that
make substantive use of a type. In all of these cases we are justified in nesting the
required Hi ncl ude directives in the component's. h fi 1e.

RasA

chararray

D dsOn
(Implied Indirect Compile-Time Dependency)

Figure 3-15: Logical IsA and HasA Relations Implying Component Dependency

Such strong physical coupling is not necessarily implied if a class HoldsA type (that
is, if it has a pointer or reference to that type as a data member), nor is it implied if the
type is used substantively in the body of a non-inline function. Such usage does not
justify forcing clients of the component to depend at compile time on its implementa-
tion types as would result from nesting the IIi ncl ude directive in the component's
header. These subtle but important distinctions will be exploited to reduce compile-
time coupling in Chapter 6.

So far we have dealt with only two or three classes at a time. Now we will infer, from
a given abstract logical representation, the physical dependencies among a somewhat
larger collection of components. The diagram in Figure 3-16 depicts a small sub-
system used to support an online glossary.

7 This form of structural inheritance is potentially unsound from a logical design stand point.
Suppose the semantics of Word require it to hold a proper subset of the arbitrary data supported by
the Stri ng base class (e.g., no space, punctuation, or control characters). Using public Inheritance,
there is no way to prevent base class functionality (e.g., Stri ng: : operator= from being used by
clients to violate this requirement (see meyers, Item 37, pp. 130-132).
Section 3.4 Implied Dependency 131

str chararray

alias wordlist
Figure 3-16: Intercomponent Logical Relationships

At the upper right of Figure 3-16, we see class Ch a r Ar ray in its own separate
component. The St ri ng class (to its left) uses Cha rArray in its implementation, so
we infer a likely physical dependency of component str on component cha ra rray:

str chararray

In this design, a Word is (perhaps inappropriately) implemented as a kind of Stri ng.

An arrow from class Word to class Stri ng is used to denote this relationship. We also
know that the IsA relationship always implies a compile-time physical dependency
between the defining components (in the same direction as the inheritance arrow).
Hence wo r'd definitely depends on s t r.

word str
132 Components Chapter 3

As we can see from Figure 3-16, Ali a s not only IsA Wo rd but also Uses Wo rd in its
interface. Notice, however, that the implied dependency of the Uses relationship and
the arrow denoting the IsA relationship point in the same direction (from Ali a s to
Wo rd). Consequently, there is no implied cyclic dependency between Wo rd and Ali as.
It would therefore be possible to use wo rd in a program without including or linking
to ali as.

(implied)
alias word

Now consider the wordl i st component of Figure 3-16, which defines two presumably
template classes Link<Word> and List<Word>. Within component wordlist we see
that there is a logical Uses-In-The-Implementation relationship between Li st<Word>
and Lin k<W0 r d >. Since these classes are already defined within the same component,
logical relationships between them cannot affect physical dependencies.

Both Li nk<Word> and Li st<Word> use Word in their respective interfaces. Either one
of these logical relationships alone would be sufficient for us to infer a likely physical
dependency of the entire wordl i st component on word. Notice again that component
wo rd can exist in a program without including or linking to wo rd 1 i 5 t, but not vice
versa.

wordlist

A component dependency diagram produced by inferring physical dependencies from

the abstract logical relationships of Figure 3-16 is shown in Figure 3-17. Actually, this
diagram does not show a complete component dependency graph. For example, it
does not explicitly show the indirect dependency of word on chararray, or of
Section 3.4 Implied Dependency 133

wordl i st on str. The complete dependency diagram is obtained if we draw each

indirect dependency as if it were a direct dependency. Such a graph is called a
transitive closure.

chararray

alias word list

Figure 3-17: Component Diagram Showing Only Direct Dependencies

The transitive closure of the dependency graph in Figure 3-17 is shown in Figure 3-
18a. All of the edges in this graph labeled with a t are called transitive edges because
their existence is implied by other edges that represent "direct" dependencies. Remov-
ing these redundant transitive edges does not lose essential information, but it does
reduce clutter and make the graph easier to understand.

.·• ·8Ii.al• :~
:·:.::;:!!·• • ·:.·
l~t!~lll!ll
(a) Complete Graph (b) Graph with Redundant Edges Removed

Figure 3-18: Transitive Closure of Direct Dependency Graph

134 Components Chapter 3

It is easy to tell from Figure 3-18b that word depends indirectly on chararray and
that wordl i st depends indirectly on word. In general, a component x DependsOn
component y if and only if there is path in the dependency graph from x to y.

To recap: logical relationships imply physical dependencies. Relationships such as

IsA and HasA between logical entities will always imply compile-time dependencies
when implemented across component boundaries. Relationships such as HoldsA and
Uses are likely to imply link-time dependencies across components. By considering
implied dependencies at design time, we can evaluate the physical quality of our
architecture long before any code is written. In Chapter 4 we discuss the characteris-
tics of component dependencies that both improve testability and promote reuse. In
the following section, we see how to extract the actual physical dependencies from
source code more efficiently.

3.5 Extracting Actual Dependencies

Suppose now that we are designing a large project, guided by implied dependencies.
After the design stage is largely complete and development is under way, we would
like to have a tool that could extract the actual physical dependencies among our com-
ponents. We could then track the actual component dependencies and compare them
with our initial design expectations.

Although it is possible to parse the source for an entire C++ program to determine the
exact component dependency graph, doing so is both difficult and relatively slow.
However, provided the design rules presented in Section 3.2 have been followed, it is
possible to extract the component dependency graph directly from the components'
source files by.parsing only the C++ preprocessor Hi nc 1 ud e directives. Such process-
ing is relatively fast as and is done by a number of standard, public-domain depen-
dency analysis tools (such as gmake, mkmf, and cdep).

The include graph generated by C++ preprocessor Iii ncl ude direc-
tives should alone be sufficient to infer all physical dependencies
within a system provided the system compiles.
Section 3.5 ' Extracting Actual Dependencies 135

To see why this claim is true, consider the following line of reasoning. If component x
makes direct substantive use of component y, then in order to compile x, the compiler
will have to see the definition supplied in y . h. The only way this can happen is for
component x to directly or indirectly include y . h. As a result of the design rules in
Section 3.2, any such direct substantive use is synonymous with a compile-time
dependency.

A compile-time The directive iii n c 1 ud e fly . h"

dependency of appears somewhere in x
x on y (other IMPLIES or in a header file included
than an include either directly or indirectly
directive) by x.

The contrapositive (that if x does not include y . h, then x does not have a compile-time
dependency on y) is certainly true, provided x compiles. .

Going the other way, the only reason component x would legitimately include the
header file of component y is if component x did in fact make direct substantive use of
component y. Otherwise the inclusion itself would be superfluous and introduce
unwanted compile-time coupling.

The directive iii n c 1 ud e "y. h" A compile-time

appears somewhere in x dependency of
or in a header file included IMPLIES x on y (other
either directly or indirectly than an include
by x. directive).

The contrapositive (that if x does not have an intrinsic compile-time dependency on y,

then x does not include y. h) should always be true-but occasionally, through human
oversight, it is not.

Guideline

A component x should include y . h only if x makes direct substantive

use of a class or free operator function defined in y.
136 Components Chapter 3

The very fact that one component includes the header of another forces a compile-
time dependency whether or not one previously existed. If we assume that all
#i ncl ude directives in a component are necessary, then it is likely that the compile-
time dependency will be accompanied by a link-time dependency (which we already
know is transitive). In other words, "substantive use" should equate to "header file
inclusion," and that substantive use almost always implies a kind of physical depen-
dency that is transitive.

The #inc 1ude graph for a set of components is just another relation that happens to
reflect the dependency among components quite accurately. If we interpret "x
Includes y. h (either directly or indirectly)" as "x DependsOn y directly," then the
relation resulting from the Hi n c 1 ude graph accurately reflects compile-time physical
component dependencies.

The design rule stating that all substantive use of a component must be flagged by
including its header file (rather than via local ext ern declarations) guarantees that the
transitive closure of the Includes relation indicates all actual physical dependencies
among components.

These extracted dependencies occasionally err on the side of being too conservative.
The dependency graph extracted in this manner may indicate additional, fictitious
dependencies brought on by unnecessary if inc 1ude directives (which should be
removed). But, provided that all the major design rules are followed, the graph will
never omit an actual component dependency.

The ability to extract actual physical dependencies from a potentially large collection
of components quickly and accurately allows us to verify throughout the development
process that these dependencies are consistent with our overall architectural plan. A
physical dependency extractor/analyzer tool is described in Appendix C.

3.6 Friendship

We now digress to discuss the subtle issues regarding friendship and how granting
friendship affects the logical interface of a class and of a component. The interaction
between friendship and physical design is surprisingly strong. Although ostensibly a
logical design issue, friendship will influence the way in which we collect logical con-
structs into components. The desire to avoid friendship across component boundaries
Section 3.6 Friendship 137

can even induce us to restructure our logical design. We refer to the material presented
in this section frequently throughout this book.

Guideline
Avoid granting (long-distance) friendship to a logical entity defined
in another component.

According to the Annotated c++ Reference Manual, "A friend is as much a part of
the interface of a class as a member is."g In making this claim, there is an implicit
assumption that the friend is inseparably tied to an object granting it friendship.

From a purely logical point of view, if a class makes a declaration of friendship, then,
according to the definition of Encapsulation (Section 2.2), that declaration is not an
encapsulated detail of the class. Anyone who defines a function whose declaration
exactly matches that of a fri end declaration within a class can gain programmatic
access to the private members of that class, provided no other function matching the
fri end declaration is defined in the same program. In that very precise sense, the
f r i end declaration itself is part of the interface of the class-the actual function defi-
nition is not.

Friendship within a component is an implementation detail of that

component.

By treating the component and not the class as the fundamental unit of design, we
gain an entirely different perspective. As long as friendship is granted locally (i.e., as
long as it is granted only to logical entities defined within the same component), the
friends are, in fact, inseparably tied to the object granting friendship.

8 ellis, Section 11.4, p. 248.

138 .Components Chapter 3

DEFINITION: A contained implementation detail (type, data, or

function) that is not accessible or detectable programmatically
through the logical interface of a component is said to be encapsu-
lated by that component.

By definition, it must be possible to detennine what is in the logical (public) interface

programmatically. Consider the equality operator defined within component stack:

int operator==(const Stack&. const Stack&);

If this operator were suddenly declared a fr i end of class Sta c k, allegedly placing the.
operator itself in the (public) interface of St a c k, then it should be possible to detect
this change programmatically-right? But, provided that the operator is defined
within the same component, granting the operator friend status has absolutely no.
effect on the logical interface of that component. In fact, from any client's point of
view, whether operator== is or is not a friend of class Stack is an encapsulated
implementation detail of this component!

To illustrate this point further, consider briefly a St ri ng class that defines (among
other things) member 0 per a t 0 r+= to implement concatenation to itself.

String {
I I ...
public:
I I ...
String(const String& string); II copy constructor
I I ...
String& operator+=(const String& rhs); II concatenate to me
};

We can now choose to implement nondestructive concatenation (+) in the same com-
ponent, without making the operator a friend:

String operator+(const String& lhs, const String& rhs)

{
return String(lhs) += rhs;
}
Section 3.6 Friendship 139

If after analysis we find it necessary to improve the performance of oper'ator+, we

can extend the encapsulation of class Stri ng by declaring operator+ a friend of
String:

String {
II...
friend String operator+(const String&, const String&):
public:
I I ...
StringCconst String& string); II copy constructor
I I ...
String& operator+=(const String& rhs); II concatenate to me
};

Declaring operator+ to be a fri end of Stri ng allows for a more efficient implemen-
tation and potentially increases the cost of maintenance, but does not affect the logical
interface of the component:

String operator+(const String& lhs, const String& rhs)

{
II clever, more efficient implementation using private members
}

There is simply no programmatic way for a client of a component to tell whether a

given logical entity defined within the component is declared a fri end of a class
defined withi~ that same component. 9

Granting (local) friendship to classes defined within the same

component does not violate encapsulation.

Granting local friendship does not threaten to expose the private details of an object to
unauthorized users. Because classes that are declared friends are defined (locally)
within the header file of the same component, anyone who tries to use the object
granting friendship will have the valid definitions of all friend classes thrust upon

9 The C++ language makes no distinction based on the location of the friend declaration within a
class. However, placing the declaration in a private area of the class reflects the component's
semantics with respect to local friendship. .
140 Components Chapter 3

them. Any attempt to redefine these friend classes will be prevented by the compiler,
which will promptly issue the error: .

MULTIPALLY DEFINED CLASS.

Defining an iterator class along with a container class in the same

component enables user extensibility, improves maintainability, and
enhances reusability while preserving encapsulation.

Locally, within a single component, friendship should be granted where necessary to

achieve proper encapsulation for the component as a whole. As with the Container/
Iterator pattern, we would always like to keep logical entities with access to our
implementation physically close to reflect the high degree of logical intimacy.
Granting friendship to logical entities outside a component, referred to in this book as
long-distance friendship, is an entirely different matter.

Granting (long-distance) friendship to a logical entity defined in a

separate physical part of the system violates the encapsulation of the
class granting that friendship.

Granting private access to another physical piece of the system leaves a hole in the
encapsulation that could be abused by plugging in a counterfeit component to obtain
access. For example, suppose the St ac kIt e r class from Section 3.1 were declared in
component stack; ter, separate from class Stack. Then there would be nothing to
stop a user of the s t ac k component from substituting his or her own component
defining a customized St a c kIt e r, and thereby obtaining private access to the St a c k
class. Once this happens, the class granting the long-distance friendship has no pro-
tection against access to its private members-its encapsulation has been violated.
Section 3.6.1 Long-Distance Friendship and Implied Dependency 141

Beside being a violation of encapsulation, long-distance friendship is a symptom of a

poorly structured design. Having physically separate logical entities intimately depen-
dent on one another subtly degrades maintainability. Specifically, long-distance
friendships reduce modularity by allowing local changes to private implementation
details to affect physically remote parts of the system.

Excessive use of even local friendship affects maintainability. Granting friendship

extends the "interface" of a class itself. The more functions that have access to the
encapsulated details of an object's implementation, the more code that will have to be
revisited (and possibly reworked) in the event of an implementation change. The
fewer the lines of code that directly access private information, the easier it is to
experiment with alternative implementations.

3.6.1 Long-Distance Friendship and Implied Dependency

Although discouraged, the possibility of granting friendship outside of a component

leads us to establish whether functions matching a fri end declaration of a class
should themselves be considered when determining the Uses relation involving that
class. The answer to this subtle question is important, but only when it comes to infer-
ring physical dependency based on the Uses relation where friendship transcends a
single component.

Friendship affects access privilege but not implied dependency.

A class is an indivisible logical unit. A free function is a distinct logical unit. Whether
the free function is or is not a friend of a class never affects any implied physical
dependency in the system.

Consider the free operator function

II barop.h
class Bar;
int operator==(canst Bar&, canst Bar&);
142 Components Chapter 3

defined in its own component, barop. Figure 3-19 shows this operator along with
class Stack and class Stacklter (now shown in separate components as well). This
free operator is neither a member nor a friend of St a c k, and therefore it clearly does
not extend the interface of class S.tack. But what exactly changes when we declare
this operator a fri end of Stack?

barop bar

Stack

stackiter stack

Figure 3-19: Related Logical Entitiesjn Distinct Components

Would 0 pe r a to r== ( con s t Bar &, con s t Ba r&) now be considered part of the inter-
face of class St a c k? If so, then St a c k uses Bar in its interface, and there is an erroneous
implied dependency of component stack on component ba r as shown in Figure 3-20.

Bar

barop

stackiter stack

Figure 3-20: Erroneously Inferred Dependency of sta ck on ba r

The physical dependencies of Stack do not suddenly assume those of barop just by
granting the operator friendship. Using a type implies a dependency on all of its mem-
bers but not necessarily on any of its friends. In particular, 0 per at 0 r== ( con s t Bar &,
con s t Bar &) is a friend of St a c k. St a c kIt e rUses St a c k, but this in no way implies that
Stacklter Uses operator==( canst Bar&, const Ba r&) either directly or indirectly.
Section 3.6.1 Long-Distance Friendship and Implied Dependency 143

Notice the direction of the arrow used to indicate the IsFriendOf relation in Figure 3-20.
The arrow indicates that ope ra to r==( can s t Ba r&, con s t Ba r&) is now permitted to
depend on St a C k in a more intimate way than before, but it does not guarantee any
actual dependency. There is no physical dependency whatsoever in the opposite direc-
tion-as would be implied by treating ope ra to r==( cons t Ba r&, can s t Ba r&) as if
it were part of the Stack's logical interface. To summarize, only access privilege and
not physical dependency is altered by granting friendship.

The importance of this principle is illustrated by the following pair of free operators
used to compare objects of type Stack and type Foa (symmetrically):

int operator==(const Stack&, const Foo&)

int operator==(const Foo&, const Stack&)

We do not need to look inside the header file for either St a c k or F00 to know that
these operators are not members and therefore are not part of the logical interface of
either class. Since these operators are not part of either class, we could define them in
an entirely separate component that could then be included by clients only when
needed. Regardless of the access privilege, the U ses-In-The-Interface relation points
in one direction, from operator to class, as shown in Figure 3-21.

foostackop stack

Figure 3-21: Acyclic Dependency of Free Operators on Classes

Now consider the highly questionable decision to add instead the following two
operator== member functions:

int Stack::aperator==(const Foo& rhs) const;

int Foo::operator==(const Stack& rhs) canst;
144 Components '.
Chapter 3

As members, these operator functions are clearly part of the interfaces of their respec-
tive classes. Each member operator uses the other class in its interface. The presence
of these operators introduces an undesirable, cyclic Uses-In-The-Interface relation-
ship between Foo and Stack as shown in Figure 3-22. No such cyclic dependency was
induced when the operators were free and defined in a separate component. Adding
free (operator) functions never affects the logical interface of any class regardless of
access because free operators, unlike members, are not an intrinsic part of any class.
(Note that making operator== a member is a poor decision in terms of purely logical
design considerations, as discussed in Section 9.1.2.)

Figure 3-22: Cyclic Dependency of Member Operators on Classes

Although granting friendship in itself never directly affects implied dependencies,

friendship can indirectly affect physical coupling. In trying to avoid the problems
associated wit~ long-distance friendships, we may find ourselves grouping several
intimately dependent logical entities into a single component, thus physically cou-
pling them (see Section 5.8).

3.6.2 Friendship and Fraud

Protecting one's implementation from unauthorized use is important for large

projects, which may span several levels of management as well as several geographi-
cal locations. In such cases, just saying, "I'm leaving a hole, but please keep out!"
doesn't work. People (particularly customers) who have access to your code at the
source level will do what they need to do to get their programs working. If using one
of your private data members will solve their problem, given half a chance they will
probably use it. If users are able to access your implementation directly, you may
meet with unwanted resistance should you try to improve it in the future.

An unscrupulous developer can gain access to private details simply by defining the
friend class locally (at file scope). The developer can then exploit these details via
inline functions, which do not have external linkage and hence will not collide with
Section 3.6.2 Friendship and Fraud 145

the legitimate function definitions, even if they are linked into the program. For the
same reason, declaring an individual non-inline free (operator) function a fri end-
even locally-is not immune to fraud via inline replacement. People actually do this
in production code. You have been warned!

Figure 3-23 illustrates the highly questionable practice of taking deliberate advantage
of the hole in encapsulation left by employing long-distance friendships. Class J ail
defines a private member rel ease() and befriends a class named Jai 1 Key, defined
outside the j ail component. The authorized J ail Key is defined within component
j ail key, which is linked into the program. A malevolent vis ito r component
declares a local version of class J ail Key hidden entirely within the vis ito r . c file.
Since this illicit version of J ail Key has no members with external linkage, it is able to
coexist silently in a program and still take advantage of the friendship afforded by
J ail. The constructor for the Vi s i to r object named "bugsy" defined in rna i n ( ) cre-
ates an instance of its own J ail Key, which on construction calls the private
r e 1 e as e ( ) method of Jail. Escape is inevitable.

Sadly, there are even easier and more heinous ways to violate encapsulation:

II felon.c
#define private public II capital offense
#include "jail.h"

void Felon: :breakOutCJail *jail)

{
jail->releaseC);
}

II

However, writing headers such as

II jail.h
#if !definedCINCLUDED JAIL) && !defined(protected) && !definedCprivate)
#define INCLUDED JAIL

class Jail { II maximum security

I I ...

lIendif

is probably going too far.

146 Components Chapter 3

II main.c
Hinclude "jail.hl!
Hinclude "jailkey.h"
#include "visitor.h"

maine)
{ II Output:
Jail jail; II john@john: a.out
JailKey key(jail): II Escape!
Visitor bugsy(jail): II john@john:
}

•
maln.c

II visitor.h II visitor.c
#ifndef INCLUDED VISITOR 1foinclude "visitor.h"
#define INCLUDED VISITOR struct JailKey { II local class
class Jail; JailKey(const Jail& jail)
class Visitor { {
I I ... jail.release();
public: } II no external linkage
Visitor(const Jail& jail); }:
... };
~~_~~~~ . #endif Visitor::Visitor(const Jail& jail)
J ail Key key ( j ail ) ; JailKey

II jail.h II jail.c
#ifndef INCLUDED_JAIL #include "jail.h"
#define INCLUDED_JAIL #include <iostream.h>
class JailKey; II not defined locally
class Jail { void Jail: :release() canst
friend JailKey; II long distance {
void releasee) canst; cout« "Escape!"« endl;
I I ...
};
# endif

jail

Figure 3-23: Example of Abusing Friendship

section 3.7 Summary 147

3.7 Summary

Developing maintainable, testable, and reusable software demands a thorough knowl-

edge of physical as well as logical design. Physical design addresses organizational
issues, beyond the scope of the logical domain, that affect readily measurable charac-
teristics such as runtime, compile time, link time, and executable size.

A component is a physical entity consisting of a . c file and a . h file, which embodies

the concrete realization of a logical abstraction. A component will typically contain
one, two, or even several classes, along with appropriate free operators needed to sup-
port the overall abstraction. A component and not a class is the appropriate unit of
both logical and physical design because it enables

1. several logical entities to represent a single abstraction as a cohesive unit,

2. consideration of both physical and organizational issues, and
3. selective reuse of translation units in other programs.

The logical interface of a component is limited to that which can be accessed

programmatically by clients, while the physical interface involves its entire header
file. Using a user-defined type, T, in the physical interface of a component, even if T is
an encapsulated logical detail, can force clients of that component to depend on the
definition of T at compile time.

Components are self-contained, cohesive, and potentially reusable units of design.

Logical constructs declared within a component should not be defined outside that
component. A component's . c file should immediately include its . h file to ensure
that the . h file will parse on its own. Consistently including the header file for each
required type definition, rather than depending on one header file to include another,
avoids problems when an encapsulated change to a component allows a Hi ncl ude
directive to be removed from its header file. To improve usability, reusability, and
maintainability, we should avoid placing constructs with extemallinkage in a compo-
nent's . c file that are not declared in its . h file. By the same reasoning, we should
avoid employing local declarations to access definitions with extemallinkage.

The DependsOn relation identifies physical (compile-time or link-time) dependencies

among components. A compile-time dependency almost always implies a link-time
dependency, and the DependsOn relation among components is transitive.
148 Components Chapter 3

We can infer a guaranteed compile-time dependency from a logical IsA or HasA

relationship across component boundaries. The logical HoldsA and Uses relations
suggest a likely link-time dependency in such cases. By taking advantage of abstract
logical relationships to infer the physical ramifications of our design decisions, we
can predict and correct physical design flaws before any code is written.

We would like to track actual physical dependencies throughout development to

ensure consistency with our initial design. Parsing all of the source code in a large
C++ system is time consuming. Provided that we have followed the major design
rules in this book, however, it is possible to infer all physical dependencies among
components from their include graph alone. A description of such a tool is provided in
Appendix C.

Finally, friendship, although ostensibly a logical issue, influences physical design.

Within a component, friendship (local) is an encapsulated implementation detail of
that component. It is common for a container class to befriend an iterator within the
same component in order to improve both usability and user extensibility, without
violating encapsulation.

Across component boundaries, friendship (long-distance) becomes part of the inter-

face of a component and results in a violation of that component's encapsulation.
Long-distance friendships further affect maintainability by allowing intimate access
to physically remote parts of a system.

Friendship directly affects access" privilege but not implied dependency. Indirectly,
however, our desire to avoid long-distance friendships will force us to package inti-
mately related logical entities within a single component, thereby coupling them
physically. Ignoring "these physical considerations invites clients to exploit the breach
of encapsulation caused by all long-distance friendships, and even by local friend-
ships, to individual, non-inline free (operator) functions.
 Physical Hierarchy

Physical hierarchy among components as defined by the DependsOn relation is analo-

gous to the logical hierarchy implied by layering. Avoiding cyclic physical dependencies
is central to effective comprehension, maintainability, testing, and reuse. Well-designed
interfaces are small, easy to understand, and easy to use, yet these kinds of interfaces
make user-level testing expensive.

In this chapter we explore how to exploit physical hierarchy to facilitate the effective
testing of "good" interfaces. We introduce the notion of level numbers to help charac-
terize components in terms of their physical dependencies. Using a complex example,
we demonstrate the value of testing in isolation as well as testing hierarchically and
incrementally. Finally, we derive an objective metric for quantifying the degree of
physical coupling within an arbitrary subsystem. This metric will help us to evaluate
the impact of various design alternatives by making the notion of physical design
quality more objective and concrete.

4.1 A Metaphor for Software Testing

When a customer test-drives a car, he or she is looking to see how well the car
performs as a unit-how well the car handles, comers, brakes, and so on. The cus-
tomer is also interested in subjective usability-how "nifty" the car looks, how com-
fortable the seats are, how plush the interior is, and, in general, how satisfying the car
would be to own. Typical customers do not test the air-bags, ball-joints, or engine
mounts to see whether they will perform as expected in all circumstances. When
150 Physical Hierarchy Chapter 4

buying a new car from a reputable manufacturer, the customer simply takes for
granted this important low-level reliability.

For the car to function properly, it is important that each of the objects on which the car
depends works properly as well. Customers do not test each part of the car individu-
ally-but somebody does. It is not the responsibility of the customer to "QA" the car.
The customer is paying for a quality product, and part of that quality is the satisfaction
of knowing that the car works properly.

In the real world, each part of a car has been designed with a well-defined interface
and has been tested in isolation under extreme conditions to ensure that it meets its
specified tolerances long before it is ever integrated into a car. In order to maintain a
car, mechanics must be able to gain access to its various parts from time to time in
order to diagnose and fix problems.

Complex software systems are like cars. All of the low-level parts are objects with
well-defined interfaces. Each part or component can be stress tested in isolation.
These parts can then be integrated, via layering, into a sequence of increasingly com-
plex subsystems-each subsystem with a test suite to ensure that the incremental inte-
gration has occurred properly. This layered architecture enables test engineers to
access the functionality implemented in the lower levels of abstraction without expos-
ing clients of the product to these lower-level interfaces. The final product is also
tested to ensure that it meets customer expectations.

To summarize: a well-designed car is built from layered parts that have been tested
thoroughly by the manufacturer:

1. in isolation,
2. within a sequence of partially integrated subsystems, and
3. as a fully integrated product.

Once assembled, these parts are easily accessible by mechanics to facilitate proper
testing and maintenance. In software, the concepts remain essentially the same.
section 4.2 A Complex Subsystem 151

4.2 A Complex Subsystem

As a concrete example of a software subsystem, consider a point-to-point wire router

for a computer-aided electronic design application. This subsystem solves a fairly
complex problem with a relatively simple description:

Figure 4-1 illustrates an instance of the point-to-point routing problem. 1 The enclos-
ing region contains three holes that a successful path may touch but not overlap. The
starting point is indicated by s and the ending point is indicated bye. One of the many
possible shortest rectilinear paths of specified width is defined by the center line,
shown in the figure connecting sand e.

1 We present this authentic example in all its detail. It is not necessary, however, to understand every
aspect of this example in order to benefit from the discussions that follow. A cursory reading will be
sufficient.
152 Physical Hierarchy Chapter 4

width
~ ~
start )

~
width < end
l'

shortest
encJosing rectilinear
regIon path

Figure 4-1: Example Problem for a Point-to-Point Router

The logical interface for a component solving this complex problem can be decep-
tively simple. The header file p2p_router. h describing the client's interface for the
point-to-point router subsystem is shown in its entirety in Figure 4-2. The (registered)
class prefix p2p_ identifies this component as belonging to the p2p package as well as
eliminating the possibility of identifier name collisions among classes belonging to
distinct packages (see Section 7.2).

II p2p_router.h
#ifndef INCLUDED_P2P_ROUTER
#define INCLUDED_P2P_ROUTER
class geom_Point;
class geom_Polygon;
class p2p_Routerlmp;
class p2p_Router {
p2p_Routerlmp *d_data_p;
II NOT IMPLEMENTED
p2p_Router(const p2p_Router&);
p2p_Router& operator=(const p2p_Router&);
public:
II CREATORS
p2p_Router(const geom_Polygon& enclosingRegion);
II Create router for specified enclosing region.
II The region must be a simple, closed polygon.
-p2p_Router();
Section 4.2 A Complex Subsystem 153

II MANIPULATORS
int addObstruction(const geom_Polygon& hole);
II Add obstruction; obstruction must be a simple, closed polygon.
II If obstruction overlaps another obstructi~n or the perimeter
II of the enclosing shape, return non-zero with no effect and 0
II otherwise. Note: Regions are allowed to touch but not overlap.
II ACCESSORS
int findPath(geom~Polygon *returnValue, const geom_Point& start,
const geom_Point& end, int width) const;
II Determine whether a rectilinear path of specified width exists
II in the current obstructed region between specified start and
II end points. Return 1 if such a path exists and 0 otherwise.
II If a path exists and returnValue is not O. store the center
II line of any shortest path in (*returnValue).
};

#endif

Figure 4-2: Complete Header File for p2p~Router

There are two user-defined types used in the logical interface of the point-to-point
router subsystem. These types (geom_Polygon and geom_Poi nt) are part of a public
package (geom) of geometric types used widely throughout the entire system. For ref-
erence purposes, the respective interfaces of geom_Poi nt and geom_Po 1ygon are
sketched in Figure 4-3.

class geom_Point {
I I ...
public:
geom_Point(int x, int y);
geom_Point(const geom_Point& point);
,....geom_Poi nt () {};
geom_Point& operator=(const geom_Point& point);
void setX(int x);
void setY(int y): class geom_Polygon {
I I ...
int x() const;
int y() const: public:
}; geom_Polygon();
geom_Polygon(const geom_Polygon& pgn);
-geom_Polygon() I};
geom_Polygon& operator=(const geom_Polygon& pgn) ;
void appendVertex(const geom_Point& point);
I I ...
int numVertices() const;
const geom_Point& vertex(int vertexlndex) const;
I I ...
};

Figure 4-3: Sketch of geom_Poi nt and geom_Po 1ygon Class Interfaces

154 Physical Hierarchy Chapter 4

An actual implementation of this subsystem involves some 5,000 lines of C++ source
code (not including comments), yet using the point-to-point router component is very
easy. A straightforward driver that runs the example of Figure 4-1 is given for
completeness in Figure 4-4. Note that the advantage of this long, linear style is its
simplicity. It is typical of drivers actually used during development and testing.

II p2p_router.t.c
II inc 1 ude p2P_ r 0 ute r . h
It If

#include "geom_polygon.h"
#include IIgeom_point.h"
#include <iostream.h>

maine)
{
geom_Polygon enclosingRegion;
enclosingRegion.appendVertex(geom_Point(O, 1000));
enclosingRegion.appendVertex(geom_Point(O, 600)):
enclosingRegion.appendVertex(geom_Point(700, -100));
enclosingRegion.appendVertex(geom_Point(2l00, -100));
enclosingRegion.appendVertex(geom_Point(2100, 100));
enclosingRegion.appendVertex(geom~Point(3000. 100));
enclosingRegion.appendVertex(geom_Point(3000, -200»);
enclosingRegion.appendVertex(geom_Point(3200, -400));
enclosingRegion.appendVertex(geom_Point(4500, -400);
enclosingRegion.appendVertex(geom_Point(5000, 100));
enclosingRegion.appendVertex(geom_Point(5000, 1000));
enclosingRegion.appendVertex(geom_Point(O, 1000));

geom_Polygon holel;
holel.appendVertex(geom_Point(800. 900»);
holel.appendVertex(geom_Point(800, 700));
holel.appendVertex(geom_Point(1400, 700));
holel.appendVertex(geom_Point(1400. 900));
holel.appendVertex(geom_Point(800. 900));

geom_Polygon hole2;
hole2.appendVertexCgeom_Point(600. 300));
hole2.appendVertex(geom_Point(800. 100));
hole2.appendVertex(geom_PointC1600, 100»);
hole2.appendVertex(geom_Point(1400, 300));
hole2.appendVertex(geom_PointC600, 300));

geom_Polygon-hole3;
hole3.appendVertex(geom_Point(2600, 900);
hole3.appendVertex(geom_Point(2900, 600));
hole3.appendVertex(geom_Point(3800, 600));
hole3.appendVertex(geom_Point(380Q, 300));
hole3.appendVertex(geom_Point(4200, 300));
hole3.appendVertexCgeom_Point(4200, 600));
hole3.appendVertexCgeom_Point(4500, 900));
hole3.appendVertexCgeom_PointC2600. 900));
Section 4.3 The Difficulty in Testing "Good" Interfaces 155

p2p~Router router(enclosingRegion);
router.addObstruction(holel);
'router.addObstruction(ho1e2):
router.addObstruction(hole3):

geom_Polygon centerline;
geom_Point start(400, 800), end(4600, 500);
int width = 400;

if (router.findPath(&centerLine, start. end, width» {

cout « centerline « endl;
}
e 1s e {
cout « IICoul d not fi nd path. I « endl;
}
}

II Output:
II john@john a.out
II { (400, 800) (400, 500) (3400, 500) (3400, 200) (4600, 200) (4600, 500) }
II john@john

Figure 4-4: Straightforward Driver for Point-To-Point Routing Problem

4.3 The Difficulty in Testing "Good" Interfaces

A truly effective use of object-oriented technology is to hide tremendous complexity

behind a small, well-defined, easy-to-understand, and easy-to-use interface. Yet it is
precisely these kinds of interfaces that, if naively implemented, can lead to the devel-
opment of subsystems that are exceedingly difficult to test.

For example, the p2p_router component (Figure 4-2) contains only four public
functions:

1. a constructor that establishes the enclosing region,

2. a destructor,

3. a function to accumulate a collection of obstructions within the enclosing

region, and
-

4. a function to determine the shortest rectilinear path of specified width

between any two points inside the region (excluding the interior of the
obstructions accumulated so far).
156 Physical Hierarchy Chapter 4

The output at the end of Figure 4-4 tells us that this component produced an answer.·
Now stop for a moment and imagine that you are a quality assurance test engineer
assigned to this project. How would you go about thoroughly testing such an interface?

First consider that in general there will be many equally good solutions for an instance
of this problem. Verifying that a solution is a rectilinear path of a given width that
connects two points in a region with obstructions is not trivial, but it can be done with-
out extraordinary effort. Verifying that a solution to this problem is optimal is, in gen-
eral, as difficult as finding the solution in the first place.

You could verify the output by trying several test cases and inspecting them by hand.
Although time consuming, manual inspection can be effective during development.·
Consider what happens when the development phase has ended and the subsystem·
moves into the maintenance/tuning phase. It would be impractical to think that you or
the developers would be willing or even able to manually review the output of every
subsystem on every release.

DEFINITION: Regression testing refers to the practice of comparing

the results of running a program given a specific input with a fixed
set of expected results, in order to verify that the program continues
to behave as expected from one version to the next.

One approach commonly used to help automate regression testing involves running a
large number of test cases through the system at the top level and capturing the results.
These results are then inspected once by hand to verify their accuracy. Before each
release, new results are obtained and compared with the original results. Presumably,
if the new output matches the old output exactly, the subsystem is correct.

A significant drawback with regression tests for many complex problems, including this
one, is that there may be multiple correct solutions. Although each of the components of
the point-to-point router subsystem may have completely predictable behavior, there is
room in the specification for the developer to alter p2p_Router's implementation in
ways that produce a different (but equally good) final result for a given input.

On a much smaller scale, consider the specification for a simple iterator on some
collection. Typically there is no constraint on the order in which the elements must be
section 4.4 Design for Testability 157

presented. The requirement is that each element in the collection be presented exactly
once. Verifying that an iterator is behaving properly in isolation is not difficult. But
when the iterat"or is embedded in the implementation of a complex subsystem (such as
that headed by the p2p_router component), the ability to test that iterator effectively
may be lost.

Although the point-to-point router is guaranteed to produce an optimal result if one

exists, many complex problems are too difficult to solve optimally in a reasonable
amount of time. In such cases, heuristic methods are employed that produce a good
(but not necessarily a best) solution. Heuristic te.chniques often take the form of an
intelligent trial-and-error strategy and are, by their nature, unpredictable. Experimen-
tation is used to determine which heuristic techniques tend to produce the best solu-
tions. Software that depends on heuristic methods is resistant to high-level regression
testing, since any improvement in the heuristics would invalidate the regression data.

Testing complex, heuristic-based software at a high-level interface is made even more

difficult because failures in the more predictable underlying components may not
cause the entire subsystem to fail outright. Instead, these insidious errors silently
degrade the quality of the subsystem's output. Since it is not always possible to verify
that the result is optimal, this degradation could easily go undetected.

Even worse than the pseudo-random behavio.-2 of heuristic-based systems is the com-
pletely unpredictable behavior associated with systems that employ asynchronous
communication. Such systems produce results that are generally not repeatable. In
these cases, high-level regression testing could be virtually useless.

Minimizing the "surface area" in our designs (i.e., providing sufficient but minimal
interfaces) is a cornerstone of good software engine~ring. Yet there is a cruel irony in
knowing that the very interfaces we strive so hard to achieve can present a formidable
barrier to conventional testing techniques. Fortunately there are techniques that we can
use to overcome these testing problems. The proverb about an ounce of prevention
being worth a pound of cure especially pertains here.

4.4 Design for Testability

A major component of designing in quality is design for testability (DFT). The impor-
tance of DFT is well recognized in the integrated circuit (Ie) industry. In many cases

2 For more on pseudo-random functionality, see rand() in pJauger, Chapter 13, p. 337.
158 Physical Hierarchy Chapter 4 :

it is impractical to test IC chips, some with over a million transistors, from the outside
pins alone.

When an IC chip is fabricated, it acts as a "black box" and can be tested only from the
external inputs and outputs (pins). Figure 4-5a illustrates the process of trying to test a
hardware subsystem w using only the interface provided to regular clients of the chip
. itself. In order to test w, it is necessary not only to figure ~ut v/hat would make a good
test suite for w, but also how to propagate that test suite through the chip to reach the
inputs of w. As if that weren't bad enough, each result that w produces must then be
propagated from the output of w to some output of the chip itself in order to observe
and verify that w has behaved correctly. Ensuring propagation of this information
requires detailed knowledge about the entire chip-knowledge that has nothing to do·
with the correct functionality of w.

A - - - 1 1.....- . . 1

B ---II~---'

c ---..,......
c

(a) Testing a Component from the System Level (b) Testing a Component Directly

Figure 4-5: Design for Testability in Integrated Circuits

One form of DFT for IC chips called SCAN is accomplished with extra pins and
additional internal circuitry provided solely for testing purposes. Using these special
features, test engineers are able to isolate the various subsystems within the chip. In
so doing they are able to gain direct access to the inputs and outputs of internal sub-
systems and to exercise their functionality directly_ In other words, this DFT
approach attempts to grant the tester direct access to a subsystem, thereby eliminating
the cost of propagating signals through the entire chip. In this way, the full functionality
of the subsystem can be explored efficiently as illustrated in Figure 4-5b, without
regard to the details of how the subsystem is used in the larger system.

When first employed, DFT was great for improving quality; however, Ie designers
did not appreciate having this additional design requirement. Not only was this an
Section 4.4 Design for Testability 159

extra consideration, but it made their designs bigger and therefore much more expen-
sive to produce. Many designers were frustrated, considering this disciplined
approach to be an infringement on their creativity.

Today DFT is an Ie industry standard. No competent hardware engineer would con-

sider designing a complex chip without directly addressing the testability issue. By
comparison, the functionality of large software systems can be orders of magnitude
more complex than would be found in even the largest integrated circuit. Surprisingly,
there is often no plan in place to ensure that the software is testable. Attempts to man-
date software testability are frequently met with the saine frustration felt in the Ie
industry over a decade ago. Often it is people rather than the technology itself who
pose the greater challenge to solving an otherwise technical problem.

With respect to testing, a software class is analogous to a real-world

instance.

Like I~ design, object-oriented software involves the creation of a relatively small

number of types, which are then instantiated repeatedly to form a working system. For
example, a S t r i n9 class is a primitive type in many software systems. Many instances
of this class may be created during a typical invocation of the system.

Both disciplines require that the functionality in these types be tested thoroughly to
ensure correct behavior when instantiated. But, unlike Ie design where each individ-
ual instance of a type must be tested for physical defects, software objects are immune
to such defects. If a class is implemented correctly, then, by definition, all instances of
that type are correctly implemented as well.

I·•.
_i_ •• rILl~~;P~
I ,
·.·.······.······.···.··.p···········
· I
.• .•
Distributing system testing throughout the design hierarchy can be
much more effective per testing dollar than testing at only the higbest-
level interface.
160 Physical Hierarchy Chapter 4

From the point of view of testing, each, software type is like a real-world instance.
Testing the functionality of a St r i n9 class is easiest and most effective if done
directly, rather than by attempting to test it as part of a larger system. And, unlike Ie
testing, we automatically have direct access to the. interface of the software sub-
system-the St r i n 9 class.

Put another way, if we have only X dollars to spend on testing, we can achieve more
thorough coverage if we distribute the testing effort throughout the system, thus test-
ing individual component interfaces directly, than we can by testing from the end
user's interface alone.

Consider again the p2p_router component of Figure 4-2. Even assuming entirely
predictable behavior, it would be ineffective to attempt to test this component entirely
from the highest level, especially given its tiny interface. In analogy to IC testing (see
Figure 4-6), this would be like trying to test a one-million-transistor microprocessor
chip with only two pins!3

Software testing is inherently easier than hardware testing because instances of a class
created within a system are no different from instances of the same class created inde-
pendently, outside that system. If a complex software subsystem were truly analogous
to an IC chip, the implementation would reside entirely within a single physical com-
ponent. If the functionality declared in p2p_router. h were implemented entirely
within p2p_router. C, we would probably be forced to violate encapSUlation by pro-
viding extra functionality in the public interface-just to enable effective testing.

3 Other kinds of Ie testing strategies such as Build-In Self Test (BIST) place additional circuitry on
the chip that can be enabled to verify that the chip is working properly without having to propagate
specific information to the interface. BIST is somewhat analogous to the use of assert statements in
software. Adding public functionality, such as testMe(), would be a more accurate analogy, but the
physical hierarchy in our software architecture allows us to achieve the same result without adding
any test-specific functionality to the interface of a component.
Section 4.5 Testing in Isolation 161

.
In out

Figure 4-6: Fictitious Highly Test-Resistant IC Chip with Only Two Pins

Fortunately, the implementation of the point-to-point router does not live in a single
component. Instead, this implementation is deliberately distributed throughout a
physical hierarchy of components. Even though the client of a p2p~Route r object has
no programmatic access to the layered objects that make up the router, it is still possi-
ble for test engineers to identify subcomponents with predictable behaviors that can
be tested and verified much more efficiently in isolation.

4.5 Testing in Isolation

In a well-designed modular subsystem, many components can be tested in isolation.

Consider a very real situation involving the point-to-point router subsystem that will
eventually support all-angle geometry. For the time being, the system is still in the
prototype stage and handles only manhattan (90-degree) angles. The point-to-point
router is object based, and so it is layered on many objects, most of which currently
support all angles. Since some of the components have not yet been upgraded to all-
angle, the p2p~router itself can accept only manhattan test cases.

Independent testing reduces part of the risk associated with software

integration.

Consider the physical architecture for the p2p~router shown in Figure 4-7. By
designing the p2p_router so that each of its subsystems can be developed and tested
individually, we can ensure that each of their upgraded functionalities is in place even
162 Physical Hierarchy Chapter 4

though they cannot be verified through the completed routers interface until some
future date. If programming errors occur, they can be detected and fixed in parallel.

Figure 4-7: Physical Dependency for a p2p_route r Implementation

An alternative, less disciplined but widely used "method" of integrating software is to

wait until all the software is in place before trying it. This is commonly referred to as
the big bang approach. The name is somewhat misleading: the anticipated "bang" is
all too often a fizzle.

Integration is where most specification errors are detected. When the integrated sys-
tem fails to perform as anticipated, the development team must scramble to diagnose
the problems. Inevitably, they will find many coding bugs not intrinsically related to
the integration itself. Independent testing could have at least allowed these coding
errors to have been diagnosed and fixed much earlier in the development process.

DEFINITION: Isolation testing refers to the practice of testing an

individual component or subsystem independently of the rest of the
system.

Testing a component in isolation is an effective way to ensure

reliability.
section 4.5 Testing in Isolation 163

At the lowest levels of a complex system, components are often heavily optimized,
increasing the likelihood of subtle errors and the need for detailed regression tests. For
example, carefully designed, object-specific memory management can often double
runtime performance. However, custom memory managers are quite error prone, and
these errors are among the most difficult to detect and repair. Instrumenting global
operators new and del et e in an isolated component test driver can ensure that the
memory-management scheme is functioning properly under a wide variety of condi-
tions, including those encountered only infrequently in practice.

Not all programs use all functionality in reusable components. For example, if a pro-
gram does not call the pop ( ) member of a Sta c k class, there is no way that pop ( ) can
be tested just by testing that program. Even if a particular program calls every func-
tion, there may be states in which objects are supposed to behave properly, but which
the surrounding software does not allow them to attain.

Consider a St r i n9 class that is developed as part of an interpreter. The interpreter

never sees a zero-length identifier, so it never tries to create an empty Stri ng to repre-
sent one. (This boundary condition would certainly be addressed by a thorough test
designed specifically for the stri ng component.) As our system evolves, we may at
some later point reuse the St r i n9 class in other parts of the same system, but in new
ways (e.g., to hold St ri ng variables). At this point an instance of an empty String can
occur within this system. The enhancement may have been made at a fairly high level
in the system, but the potential bug exists at the lowest level-in the St r i n 9 class-
which has been working "perfectly" for quite some time!

In a large project, the author of the St r i n9 class is probably not the same individual
as the one whose valid enhancement exposes the problem. Detecting and then repair-
ing such bugs, not to mention the frustration that ensues, is far more expensive than
simply avoiding them in the first place through early, component-level testing in
isolation.

It would be redundant and unnecessarily costly for every system that uses a library
facility such as i ostream to have tests to verify that the needed i ostream functional-
ity is working properly. People have come to assume that i ostream does work as
intended. For large systems, there will probably be many application libraries devel-
oped in house. No single executable will make use of all of this functionality, yet all
of it should be tested thoroughly in isolation.
164 Physical Hierarchy Chapter 4

We can avoid the redundancy by grouping the testing effort with the components them-
selves. In so doing, one extends the notion of object-oriented design to include, as a
single unit, not only the component but also the supporting tests and documentation.
Furthermore, well-written component-level tests can facilitate reuse by providing pro-
spective users with a suite of small but comprehensive examples. The functionality
supplied by each component can now be tested thoroughly in a single place; clients
who depend on these components may reasonably assume they are reliable.

Isolation testing is ideal for identifying low-level problems that result from enhance-
ments and is especially useful for porting a system to new platforms. These low-level
tests ensure the preservation of basic functionality and make it easy to track down any
discrepancies. Occasionally defects escape local detection and are caught by tests at
higher levels. The low-level component test should be updated to expose the errant
behavior before the defect is repaired. Doing this will both facilitate the repair and
preserve modularity by making the testing of this component independent of any
particular client.

There is a point of diminishing returns to testing in isolation. For example, placing the
definition of aLi n k class for a simple Lis t object in a distinct component so that it
may be tested in isolation is absurd for two reasons:

1. The normal operation of aLi s t object will thoroughly exercise the

Lin k's functionality.

2. The additional component will unnecessarily increase the physical com-

plexity of the system, making it more difficult to understand and maintain.

Determining this point for component-level isolation testing should be done objec-
tively, based on a costlbenefit analysis, not solely by how much a given developer
loathes (or enjoys) testing.

4.6 Acyclic Physical Dependencies

For a design to be tested effectively, it must be possible to decompose the design into
units of functionality whose complexity is manageable. A component is ideal for this
purpose. Consider the header files for three components cl, c2, and c3 depicted in
Figure 4-8. Note that we have declared class C1 in component headers c2. hand c3. h
without providing its definition because it is not necessary to define a class that is
returned by value in order to declare that function.
section 4.6 Acyclic Physical Dependencies 165

II c1.h II c2.h II c3.h

#ifndef INCLUDED_C1 #ifndef INCLUDED_C2 #ifndef INCLUDE_C3
#define INCLUDED_C1 #define INCLUDED_C2 #define INCLUDE_C3
class C1; class C1; class C2;

class C1 { class C2 { class C3 {

I I ... I I ... I I ...
public: public: public:
C1 f(); C1 g(); C1 h(const C2& arg);
}; }; };

4fendif #endif #endif

c1.h c2.h c3.h

Figure 4-8: Components with Acyclic Implied Dependencies

We can observe (Section 3.4) that there are no implied dependencies of clan any other
component. Class C2 uses class C1 in its interface. Therefore it is likely that component
c2 depends on component cl, but, we hope, not on c3. Class C3 uses both C2 and (1 in
its interface, and so c3 is likely to depend on both c2 and cl. The implied dependen-
cies in this system form a directed acyclic graph (DAG) as shown in Figure 4-9a.

Component dependency graphs that contain no cycles have very positive implications
for testability, but not all component dependency graphs are acyclic. To see why, con-
sider what would happen if we changed the return type of (1 : : f from a C1 to a (2 as
follows:

class C1 {
I I ...
public:
II C1 f(); II old
C2 f(); II new
}:

Now (1 uses (2 in its interface and (probably) depends on it. The implied component
dependency graph for this modified system now has a physical cycle, and is shown in
Figure 4-9b.
166 Physical Hierarchy Chapter 4

redundant edge
/'
'"
/'
/'
/'
\ ...... .
\ .

c2 \ \ c1
\ \
\ \
\ \

cycle

c1

(a) Acyclic Dependencies (b) Cyclic Dependencies

Figure 4-9: Acyclic versus Cyclic Physical Dependencies

Systems with acyclic physical dependencies (such as the one shown in Figure 4-9a)
are far easier to test effectively than those with cycles. Whenever the component
dependencies in a system are acyclic, there is (at least) one reasonable order to go
about testing the system. Since component c 1 depends on nothing else, tests to verify
its functionality in isolation can be written first. Next we see that component c2
depends only on component cl. Because we were able to write effective tests for cl,
we may presume c 1 to be functioning properly. We can now write tests for the func-
tional value added by c2. We need not retest the contribution of cl since that function-
ality is already covered. Then we look at c3 which depends on both cl and c2.
Because we presumably have already written tests to verify the functionality supplied
by both cl and c2, we need address only the additional functionality implemented in c3.

4.7 Level Numbers

In this section we introduce a method for partitioning components based on their

physical dependencies into equivalence classes called levels. Each level is associated
with a non-negative integer index, referred to in this book as the level number. The
next few paragraphs describe the origins of level numbers and how they were used in
their original context. Then we apply these well-established concepts in a new con-
text: software engineering.
section 4.7.1 The Origin of Level Numbers 167

4.7.1 The Origin of Level Numbers

The notion of level numbers is borrowed from the field of digital, gate-level, zero-
delay circuit simulation. 4 Here, a gate implements a low-level block of Boolean func-
tionality. Each gate has two or more connection points called terminals. A circuit
consists of an interconnected collection of gates. Like a gate, a circuit has both input
terminals and output terminals. Primary inputs are inputs to the circuit itself. These
inputs are connected to the inputs of some of the gates within the circuit by pair-wise
terminal connectors called wires. The outputs of these gates are connected by wires to
the inputs of still other gates, and so on. A simple circuit with four primary inputs
(a, b, c, and d) is illustrated in Figure 4-10a.

".A--+--Y

(a) Circuit Without Feedback (b) Circuit With Feedback

Figure 4-10: Logic Circuits Without and With Feedback

Simulating a circuit involves setting its primary inputs with logical values and then
evaluating each of the (layered) gates in tum. But before any particular gate can be
evaluated, we must make sure that its inputs are valid by ensuring that all gates that
feed this particular gate have already been evaluated.

A circuit is a kind of graph. Here, gates and primary inputs are treated as vertices of a
graph, and wires are treated as (directed) edges. 5 The level number in this context

4 The zero-delay approximation is used primarily in a special kind of circuit simulator known as a
fault simulator. The discovery of this analogy between hardware and software arose, in part, from
the author's Ph.D. research at Columbia University with Professor Stephen H. Unger.
5 The gates themselves impose the edge direction, which reflects the dependency of the gate on its
input source (e.g., either a primary input or the output of another gate in the circuit).
168 Physical Hierarchy Chapter 4

indicates the longest path from a particular gate to a primary input. Primary inputs are
defined to have a level of O. By evaluating these gates in order of increasing levels, we"
can guarantee that every gate's inputs will be valid.

Primary input values are assumed, and do not require evaluation. During simulation,
level-l gates are fed only by primary inputs. These gates are evaluated first, in arbi-
trary order. Next to be evaluated are alllevel-2 gates. Since level-2 gates are fed only
by one or more level-l gate (and possibly also by primary inputs), we are assured at
this point that all inputs for level-2 gates have been evaluated. Since a gate at level N
depends only on levels [0 ... N-l] for its inputs, evaluating gates in levelized order
guarantees a successful simulation.

In Figure 4-10a, a level-l OR-gate feeds the only input of the NOT-gate, making it a
level-2 gate. The AND-gate is fed both by a level-l OR-gate and a level-2 NOT-gate. The
longest path from the AND-gate to a primary input is 3 (through the NOT-gate to primary
input c or d). The AND-gate belongs to the highest level, 3, and is evaluated last.

Every directed acyclic graph can be assigned unique level numbers; a

graph with cycles cannot.

Notice that, with the pair of cross-coupled NOR-gates in Figure 4-10b, the longest path
from either gate to either primary input (r or s) is unbounded. This circuit cannot be
levelized-that is, it cannot be assigned unique level numbers. The property that
makes a circuit levelizable is that it has no feedback. This lack of feedback makes the
circuit qualitatively easier to understand, develop, analyze, and test. For these reasons,
feedback is used in large systems only under very restricted circumstances. For com-
pletely analogous reasons, a "lack of feedback" is exactly the property we would like
our software designs to possess.

DEFINITION: A physical dependency graph that can be assigned

unique level numbers is said to be levelizable.
Section 4.7.2 Using Level Numbers in Software 169

4.7.2 Using Level Numbers in Software

Turning back to software engineering, if the component dependencies in a software

system happen to form a DAG, we can define the level of each component.

DEFINITION:
Level 0: A component that is external to our package.
Levell: A component that has no local physical dependencies.
Level N: A component that depends physically on a component
at level N-l, but not higher.

In this definition, we assume that all components outside our current package6 (e.g.,
i ostream) have already been tested and are known to function properly. These com-
ponents are treated as "primary inputs" and have a "level" of O. A component with no
local physical dependencies is defined to have a level of 1. Otherwise, a component is
defined to have a level one more than the maximum level of the- components upon
which it depends.

Figure 4-11 shows the component dependency diagram from Figure 3-17 of Section
3.4, which happens not to have any cycles, and hence is levelizable. The level number
is shown in the upper right comer of each component. Component c ha r a r ray does
not depend on any other components locally but does depend on the standard library
components (which are all assumed to be at level 0), so chararray has a level of 1. A
level-l component (such as cha ra rray) that depends only on compiler-supplied
libraries is called a leaf component. Leaf components are always testable in isolation.

6 Assume for now that package means the current project directory.
170 Physical Hierarchy Chapter 4

o
(external or C++
standard library
components)

chararay

alias wordlist

Figure 4-11: Levelized Component Dependency Diagram

Component str depends only on chararray. The level of str is 2, one more than that
of chararray. Component word depends on str (and indirectly on chararray). Since
s t r has a level of 2, wo rd has a level of 3. Since wo rd is at level 3, and the only com-
ponent on which ali a 5 depends directly is wo rd, ali a 5 is at level 4. The wo rd 1 i 5 t
component also depends directly on word but does not depend on al i as, so wordl i st
is also at level 4.

DEFINITION: The level of a component is the length of the longest

path from that component through the (local) component dependency
graph to the (possibly empty) set of external or compiler-supplied
library components.

With a levelized diagram it is easy to tell what components in this system are testable
in isolation. In the example of Figure 4-12 there is only one independently testable
Section 4.7.2 Using Level Numbers in Software 171

component: chararray. By starting at the lowest level (i.e., 1) and testing all compo-
nents on the current level before moving to the next higher level, we are assured that
all the components on which the current component depends have already been tested.
In the example of Figure 4-11, we can test either wo r d1 i 5 t or ali a 5 last, but the rest
of the testing order is implied by the level num-
bers.

In most real-world situations, large designs must be levelizable if they

are to be tested effectively.

Notice that the term levelizable applies to physical, not logical, entities. Although an
acyclic logical dependency graph might imply that a testable physical partition exists,
the level numbers of (physical) components, along with our design rules, imply a via-
ble order for effective testing. Moreover, Figure 4-11 identifies what subsystems can
be reused independently. Figure 4-12 indicates the other components that must
accompany the reuse of any of these components.

To test or reuse You also need

cha ra rraYl:
string2: chararraYl
word 3: string2 chararraYl
alias4: word 3 stri ng2 chararraYl
wordl i st 4 : word 3 st ri ng2 cha ra rraYl

Figure 4-12: Independently Reusable Subsystems

Another significant advantage to levelizable designs is that they are more easily
comprehended incrementally. The process of understanding a levelizable design can
proceed in an orderly manner (either top down or bottom up). Not all subsystems
formed by hierarchical designs are reusable. But, to be maintainable, each component
must have a well-defined interface that can be readily understood, regardless of how
general its applicability.
172 Physical Hierarchy Chapter 4

Of course, not all designs are levelizable. Sometimes whether or not a design is level-
izable is not immediately obvious from a logical diagram. Consider the diagram of
Figure 4-13. Can you tell from this diagram whether or not the components in this
design are levelizable?

Figure 4-13: Is This Design Levelizable?

The indicated logical relationships in this design do not imply cyclic physical depen-
dencies among any of the components. In fact, our design rules ensure that there can be
no hidden physical dependencies (e.g., on external global variables). Figure 4-14 shows
the implied component dependencies and the resulting component level numbers for
this design.
Section 4.7.2 Using Level Numbers in Software 173

Figure 4-14: Component/Class Diagram

The component/class diagram is cluttered and contains more information than needed
to understand the physical structure of the system. If we rearrange the placement of
the components and eliminate the logical detail, we obtain the strikingly lucid compo-
nent dependency diagram of Figure 4-15.

There is one redundant edge in the diagram of Figure 4-15. Component wordexbui 1der
depends directly on components di rectory, fi 1e, and node. As we know from Section
3.3, the DependsOn relationship is transitive. Since di rectory (and fi 1 e also) depends
on node, the dependency of wordexbui 1der on node is implied and can be removed
without affecting level numbers. The diagram in Figure 4-15 is clearly acyclic and
typical of those for subsystems that address a specific application. At this level of
abstraction, the design appears to be sound.
174 Physical Hierarchy Chapter 4

Level 5:

Level 4:

Level 3:

Level 2:

Levell:
*redundant transitive edge

Figure 4-15: Component (Direct) Dependency Diagram

One of the great values of this ~alysis is that, after untangling the component depen-
dency diagram, we were able to make a substantive, qualitative comment about the
integrity of the physical design without even the tiniest discussion of the application
domain. Simple tools to help automate this process are easy to write, and have proven to
be invaluable for large projects. Appendix C describes a simple component-dependency
J

analyzer.

4.8 Hierarchical and Incremental Testing

Components are the fundamental building blocks of a system. Every component is

different. Each is an "instance" of the physical design pattern: "component.." Out-
wardly, they all have the same basic physical structure-a physical interface (. h file)
and a physical implementation (. c file).

In this sense, implementing and testing a software system is like building a house.
After the overall architectural design is complete, the bricks (i.e., the components, not
objects) are put in place one by one. The successful addition of each brick depends
not only on its own integrity but also on the integrity of the mortar used to integrate
the brick with the lower-level bricks on which this brick depends. It is easy enough to
inspect each brick for defects along the way. But once complete, the house is often
large and complex, presenting too many barriers to inspect each detail.
section 4.8 Hierarchical and Incremental Testing 175

DEFINITION: Hierarchical testing refers to the practice of testing

individual components at each level of the physical hierarchy.

In the house-building analogy, a brick represents a unique component (i.e., one or

more classes), not individual instances. In practice, thorough testing requires testing
the integrity of each component before putting it in place. Exercising a component
before installation in no way precludes the possibility of more thorough testing in iso-
lation later. Testing component interfaces at each level of the physical hierarchy is
referred to in this book as hierarchical testing.

Hierarchical testing requires a separate test driver for every component.

In this approach, a separate test driver for each component is created by the developer
concurrently with the component itself to exercise and verify functionality imple-
mented in that component. Not only is this test driver used extensively during devel-
opment, but it is later ~ade available to quality assurance (QA) in order to help
describe the intended behavior of the component that it verifies.

Each component can be tested using an individual test driver that exercises the func-
tionality implemented in that particular component. Physical dependency governs the
order in which tests are developed and run. Level numbers serve both to characterize
the relative complexity of a component locally within a package and to provide an
objective strategy for testing.

Individual drivers are necessary in order to ensure that physical design rules are fol-
lowed-otherwise we will be unable to demonstrate that functionality declared within
a component is available solely within the subset of components indicated by that
component's dependency graph. To illustrate why this is so, consider the design-rule
violation (shown in Figure 4-16), where component a defines a class A with member
function f ( ), and a component b (layered on a), which illegally implements A: : f ( ).
176 Physical Hierarchy Chapter 4

As illustrated in Figure 4-16a, a single test driver that links to both a and b is inca-,.
pable of detecting this major design rule violation. As far as anyone can tell from the:
dependency graph, component a is independent of component b and therefore can be
reused independently of b. If someone tries to reuse component a independently of b
and calls f ( ), A: : f will show up as an undefined symbol at link time.

In Figure 4-16b, distinct drivers are provided to exercise the functionality in each
component. When linking the driver for component a, component b is deliberately
excluded from the link process. If the driver for a is at all thorough (i.e., calls each
function at least once), then if A: : f is not defined, the error will be caught at link time
-that is, without even having to run the driver. This same technique also serves to
detect components that are not levelizable.

DriverAB DriverB

ab.t.c b.t.c

DriverA

a.t.c

a a
(a) One Driver for Many Components (b) One Driver per Component

Figure 4-16: The Need for Individual Component Drivers

Another compelling reason for insisting on individual drivers is that a single compo-
nent typically provides ample functionality for a test driver to exercise thoroughly.
Lumping tests for several components within a single driver would lead to excessively
large (or, more likely, inadequate) tests.
Section 4.8 Hierarchical and Incremental Testing 177

Figure 4-17 illustrates the abstract physical structure of the hierarchical testing
strategy. Each component at level 1 can depend on only external components (all of
which are at level 0). Therefore each component at level 1 can be tested independently
of all other (local) components.
•
•
•

Level 3:

Level 2:

driver2 driver4

Levell:

Level 0: components from other packages

Figure 4-17: Hierarchical Testing Strategy

As we proceed to higher levels of the physical design hierarchy, the complexity of the
subsystems will grow, often exponentially. This explosive growth implies that we will
soon reach the point where tests designed to cover the complete behavior of a high-
level interface will be too difficult to write or take too long to run.

DEFINITION: Incremental testing refers to the practice of deliber-

ately testing only the functionality actually implemented within the
component under test.
178 Physical Hierarchy Chapter 4

Our hierarchical approach makes it unnecessary to retest the internal behavior of

lower-level components. If instead we attempt to test only the functional value added
by a given component, the test complexity for each component is more likely to be
kept to a manageable level. The practice of targeting only the new functionality added
by a given component is referred to in this book as incremental testing.

Testing only the functionality directly implemented within a

component enables the complexity of the test to be proportional
to the complexity of the component.

Since we can assume that the components at lower levels are supplying objects that •
are working properly, the task of incremental testing is often reduced to testing the
way in which these lower-level objects combine to form higher-level objects. Writing
incremental tests is not always easy in practice, and requires intimate knowledge of
the implementation of the component.

For example, suppose a user-defined type Xis layered upon three other types, A, B, and
C, each of which lives in a separate component. Figure 4-18a shows part of the defini-
tion for class X. From this partial header we can observe the logical uses relationships
of Figure 4-18b. Now, given that each class resides in a separate component, we can
infer the component dependencies shown in Figure 4-18c.

In this highly simplistic example, testing functions f and 9 of class X amounts to veri-
fying that functions X : : f and X : : 9 are properly hooked up to the appropriate underly-
ing functions c : : U and C: : v, respectively. Since component c is at a lower level than
component x, we can assume that c has already been tested and is internally correct,
making it unnecessary to retest C: : u or c: : V in the driver for component x. By con-
trast, the implementation of X: : h is substantial, and therefore is where most of the
testing effort for this component should be focused.
Section 4.8 Hierarchical and Incremental Testing 179

class X {
Ad_a;
B d- b·,
C d_c;
public:
/ / ...
int f() { return d_c.uCd_a); }
i nt 9 () { ret urn d_c. v (d_a, d_b); }
int hC);
};

(a) Definition of Class X

x
B
b
(b) Logical Relationships (c) Physical Relationships
Among Classes Among Components

Figure 4-18: Analyzing a Layered Object for Testing Purposes

DEFINITION: White-box testing refers to the practice of verifying

the expected behavior of a component by exploiting knowledge of its
underlying implementation.

Exploiting knowledge of the implementation of the component is a genre of testing

known as white-box testing. White-box testing allows the tester to approach nearly
complete internal code coverage with a much smaller test driver by carefully choosing
test cases that exercise all of an object's internal functionality.
180 Physical Hierarchy Chapter 4

·White-box tests are effective at helping the developer flush out low-level program-
ming errors such as simple coding errors, and often even basic algorithmic errors
resulting in memory leaks and even forced program terminations. Since white-box
tests are implementation dependent, a complete reimplementation of an underlying
object may render such tests ineffective.

White-box testing and 100 percent code coverage are necessary but are not sufficient
to ensure high-quality components. For example, if, as a developer analyzing a prob-
lem, I miss a special case that requires extra processing, it is not likely that the omis-
sion would be uncovered through white-box testing alone.

DEFINITION: Black-box testing refers to the practice of verifying

the expected behavior of a component based solely on its specification
(i.e., without knowledge of its underlying implementation).

Unlike the white-box test that verifies that the code works as the developer intended,
the black-box test verifies that the component satisfies its requirements and complies
with its specification.

Black-box testing is driven directly from the component's requirements and specification.
Black-box testing is, for the most part, independent of implementation. Black-box testing
is also appropriate for an independent tester, say from a QA department, who must under-
stand the behavior and proper use of the component from its documentation alone.

As suggested by Figure 4-19, black-box and white-box testing are complementary

techniques with some degree of overlap. Both are important, and each addresses
separate aspects of quality. White-box testing tends to ensure that we have solved a
problem correctly, and black-box testing helps to make sure that we have solved the
correct problem.

Development will tend to emphasize white-box testing to ensure reliability. QA will

. probably use white-box testing to ensure coverage, but will also employ black-box test-
ing to verify the accompanying specifications and documentation. Moreover, black-box
tests may be given to clients as acceptance tests in order to demonstrate functionality,
whereas white-box tests, being implementation dependent, would probably remain in-
house. Thorough tests of complex components will make effective use of both strategies.
Section 4.9 Testing a Complex Subsystem 181

Black-Box Testing White-Box Testing

Figure 4.. 19: Defects Detectable Through Testing

One of the appealing properties of incremental testing is that the difficulty of testing
any given component is roughly proportional to the functional value added by that
component itself rather than to the combined complexity of the lower-level compo-
nents on which that component depends. Regardless of how extensive the functional-
ity in components a, b, and c might be, it may be possible to write a relatively short
but thorough incremental test for component x because X: : f and X: : 9 merely propa-
gate information to and from a working C subobject.

To summarize this section: we want the complexity of the test to correspond to the
complexity of the component under test. We want to test all leaf components in isola-
tion. All higher-level components are tested assuming the lower-level components on
which they depend are internally correct. This incremental, hierarchical strategy
allows us to focus our testing effort where it can do the most good, and to avoid the
redundancy of retesting already tested software.

4.9 Testing a Complex Subsystem

Let us- return once again to the point-to-point router example of Figure 4-2. As dis-
cussed earlier, the interface for p2p_router is difficult to test effectively. It is pre-
cisely for these kinds of interfaces that hierarchical testing is most needed to ensure
quality.

An actual implementation of this· example is distributed throughout the levelizable

hierarchy shown in Figure 4-20. Some but not all of the components in this subsystem
are reused by other components at higher levels. Both the geom_poi nt and
182 Physical Hierarchy Chapter 4

geom_po 1ygon components belong to a separate package, geom, and are assumed by
the p2p package implementor to be internally correct. These reusable library compo-
nents account for a nontrivial portion of the router's implementation.

Component
level
4

C++ Runtime Library External geom Package o

Figure 4-20: Component Dependency Diagram for Point-to-Point Router

Let us assume that in our p2p_router subsystem, each of the lowest-level compo-
nents has predictable behavior and is eminently testable. The level-l components are,
as ever, testable in isolation-independently of any other p2p components. Each of
the level-2 components in this subsystem depends on at most two level-l components.
Each of the level-2 components implements an appropriate amount of additional func-
tionality that, in combination with the already-tested lower-level functionality, is not
difficult to understand and verify.

The p2p_router component insulates its clients of the router from all details of its
implementation, pushing much of its implementation down into the p2p_routerimp
component. In tum, p2p-,-routerimp serves to expose to test engineers subfunctional-
ity that would otherwise be inaccessibly defined within p2p_router. c.

In the actual implementation, p2p_router implements less than 10 percent of the solu-
tion; its job is primarily to coordinate the functionality implemented in the lower-level
Section 4.10 Testability versus Testing 183

components of the p2p subsystem. We have improved maintainability by carefully

distributing the implementation of the functionality of this complex component
across a hierarchy of some 10 other local subcomponents, each with independent,
well-defined interfaces, and each implementing a manageable amount of predictable
functionality.

To summarize: we have designed in testability for a component that is potentially dif-

ficult to test by factoring its implementation into a levelizable hierarchy of indepen-
dently testable (and perhaps reusable) components. Distributing the testing effort
throughout the router subsystem will exponentially reduce the amount of regression
testing that would be needed at the highest level to achieve the same degree of quality.
Human validation is expensive and prone to error, and is frequently omitted due to
lack of time and resources. However, the levelized hierarchy enables the predictable
behavior of the subcomponents to be tested using more robust methods that do not
require human intervention.

In short, hierarchical physical implementations of complex subsystems can be both

more reliable and less costly to test than non-hierarchical alternatives.

4.10 Testability versus Testing

Testability and testing are not the same thing. In fact, they are largely independent
aspects of quality. By testable, we mean that there is an effective test strategy that will
allow us to verify that the functionality indicated by the interface (along with support-
ing documentation) is realized by the implementation. By tested, we are saying that
the product has demonstrated that it now conforms to its specifications. Testable is
something we strive to make our products from the moment we start our design.
Tested is a state our product must attain before we release it to our customers. Testing
is something we do all along the way.

Thorough regression testing is expensive but essential; the appropriate

time to create thorough regression tests is tied to the stability of the
subsystem to be tested.
184 Physical Hierarchy Chapter 4

Knowing when and how much to test is an engineering trade-off. The more thorough
the developer is at testing the code as it is being implemented, the less likely it will be
that unforeseen bugs will affect the development schedule down the road.

On the other hand, developing thorough tests is time consuming and can significantly
increase the up-front cost of development. Often this extra effort is more than
compensated by reduced time spent in maintenance, future enhancements, and even
current development.

Unfortunately, it is inevitable that the interfaces of many components will change sub-
stantially during the early stages of the development process. Some components will
split apart, others will merge together, and still others will disappear entirely. Conse-
quently, developing thorough regression tests at the preliminary stages of a project
may in some cases tum out not to be cost-effective.

As a project progresses, various components will become mature. The interfaces to

these components will become more stable-they will change less frequently than,
say, once a month. It is at this point that it may be appropriate for QA to make a sec-
ond pass at writing thorough, systematic regression tests to validate these components
and report any missing or ambiguous documentation.

As long as developers design their components to be testable and provide sufficient

and appropriate documentation, it should be fairly straightforward for test engineers
7
to write detailed systematic tests to verify the functionality supplied by each component.

If developers do not consider testability when designing their systems, then the testing
process may not be straightforward or effective. In order to facilitate efficient testing,
the testability of a system must be in place long before its components are ever tested.

4.11 Cyclic Physical Dependencies

Often designs begin with acyclic dependencies and then, as they evolve, cyclic depen-
dencies creep in during enhancements. For example, consider adding to class C1 in
Figure 4-8 of Section 4.6 the member 9 ( ) returning a C2 by value as follows:

7 See marick for a thorough treatment of systematic testing.

Section 4.11 Cyclic Physical Dependencies 185

class (1 {
I I ...
public:
Cl f();
C2 g(); II new
};

Member 9 ( ) introduces an additional dependency, resulting in the cycle of Figure 4-

9b. With the addition of this function, components c 1 and c 2 must "know about" each
other (i.e., their respective components must include each other's header files) and are
therefore mutually dependent. It will no longer be possible to test or use either C1 or
C2 without the other.

Cyclic physical dependencies among components inhibit understanding,

testing, and reuse.

Having cyclic physical dependencies among components is undesirable, not only

because it makes them hard to test and impossible to reuse independently, but also
because it makes them much more difficult for people to understand and maintain.
Once two components are mutually dependent it is necessary to understand both in
order to fully understand either.

Guideline

Avoid cyclic physical dependencies among components.

It is not uncommon for closely related classes to be mutually dependent; however,

these classes will properly reside in a single component. If we find that two (or more)
components c1 and c2 are mutually dependent, we have three alternatives:

1. Repackage c1 and c2 so they are no longer mutually dependent.

2. Physically combine c1 and c2 into a single component, c12.
3. Think of eland c 2 as if they were a single component, c 12.
186 Physical Hierarchy Chapter 4

The best solution is to correct cyclic dependencies before they happen; or, if they do
creep in, to detect and correct them as soon as they occur. Chapter 5 addresses tech-
niques for restrtlcturing a cyclically dependent design to eliminate the cycles while
preserving the intended behavior.

Merging components into a single component is the right solution when the objects in
the combined abstraction are naturally tightly coupled and other issues -do not over-
ride. If one class befriends another, this -would further suggest that the classes belong
in the same component (see Section 3.6.1). Merging tightly coupled, cohesive compo-
nents also has the welcome benefit of reducing the number of components, and hence
the physical complexity of the system, without further compromising testability or
independent reuse.

Occasionally a single, tightly coupled abstraction will be deemed too large to fit in
one component and will be split into mutually dependent components. Most of the
time, however, the tightly coupled part of the abstraction can be isolated from the rest
of the implementation and placed in a single component, which in tum depends on
other independent components. These independent components can now be tested
thoroughly in isolation (see Section 5.9).

Level 2

r- - - - - - - - - - - - - .,
I I
c12 Levell
I I
L
- - - ------ -- - -- .J

Figure 4-21: Two Mutually Dependent Components Treated as One

If no other solution is forthcoming, we can mentally treat mutually dependent components

as if they were just one big component, as illustrated in Figure 4-21. This approach is
easy in the short term but is the least desirable alternative for the long term. These
physically separate yet tightly coupled components must artificially be treated as a:
Section 4.12 Cumulative Component Dependency 187

single physical unit, which detracts from the uniformity of a maintainable design.
Although such dependencies are undesirable, the overall testability of a system will
not be lost so long as the number and size of such "blobs" are kept to a minimum.

4.12 Cumulative Component Dependency

We now formalize our discussion of designing in quality by providing a metric

referred to in this book as the cumulative component dependency (CCD) of a sub-
system that is closely tied to the link-time cost of incremental regression testing. More
generally, the CCD provides a numerical value that indicates the relative costs associ-
ated with developing and maintaining a given subsystem.

DEFINITION: Cumulative component dependency (CCD) is the sum

over all components Ci in a subsystem of the number of components
needed in order to test each Ci incrementally.

Linking large programs takes a long time. Typically, developers will need to link a
single component many times in the process of creating both the component and its
test driver. After that, the component will need to be linked to its driver whenever
regression tests are run. For small projects, link times are comparable to the compile
times of individual components. As projects get larger, the link time grows to be much
larger than the time needed to compile even the largest of components.

Most of our development time is spent on low-level components, primarily because

there are simply a lot more low-level components than high-level ones. These low-
level pieces of the system can be intricate and are sometimes selected for performance
tuning. It is to our advantage to streamline the process of developing, testing, and
maintaining low-level components.

For the sake of this discussion, let's say that the dependencies in a design formed a
perfect binary tree. Just over half of the components would be at levelland could be
tested in complete isolation. Another quarter would each depend on two leaf compo-
nents. If we let L represent the number of distinct levels in the tree, then only one of
the 2L-l components would actually depend on all the rest. Although real designs are
not nearly so regular, the advantage of testing a hierarchy of components with acyclic
dependencies remains clear.
188 Physical Hierarchy Chapter 4

Consider the costs associated with developing a set of components. For the moment,
let's assume that link time is proportional to the number of components being linked
together. 8 For instance, if linking one component to a test driver takes 1 CPU second,
then linking five components would take roughly 5 CPU seconds.

In the presence of cyclic dependencies, it may be necessary to link in most or all of

the components in order to test anyone of them. It is not necessary that every compo-
nent depend directly on every other component for a design to be fully interdepen-
dent. 9 Suppose our system is very tightly coupled and each component is either
directly or indirectly dependent on all the others. If we let N represent the number of
components in our system, the cost of linking anyone of these components to its test
driver is proportional to N. The link cost alone of building all N test drivers for these
components is then proportional to N 2 • This fact explains why linking often dominates
the cost of running thorough regression tests for large systems.

Let N be the number of components in the system.

total number) ( link-time cost)
CCDCyclically (N) - ( of components· of testing a
Dependent
Graph
component

-- N • N

8 This assumption is of course only a crude approximation, since link cost will clearly be affected by
variation in component sizes and by the structure of the function-call hierarchy.
9 A fully interdependent design has a direct-dependency graph that is "strongly connected" but not ,
necessarily "complete." See abo, Section 5.5, p. 189 and Section 10.3, p. 375 for formal definitions
of these respective terms.
Section 4.12 Cumulative Component Dependency 189

Now consider what would happen if our dependencies were acyclic and formed a
binary tree. Now, not all components have equal link cost. Components at level 1
could be linked to their respective test drivers in unit time (e.g., 1 CPU second). Fully
half of the link cost associated with component testing could be virtually eliminated.
Each component at level 2 would depend on two components at levelland comprise
a subsystem of size 3 (it would take 3 CPU seconds to link). That is, another quarter
of the test cost associated with linking could be reduced dramatically (by a factor of
N/3). Only one component in this hypothetical system, the root, would require the full
N CPU seconds of link time previously required by each of the N components.

Mathematically we can show that the total link cost to incrementally test a system
whose physical dependencies form a binary tree is proportional to N log (N) instead of
N 2 (see Figure 4-22). For example, in the case with 15 components,

CC~alanced
Binary
(15) = (15+ 1) • (log2(15 + 1) - 1) + 1 = 49
Tree

Acyclic physical dependencies can dramatically reduce link-time

costs associated with developing, maintaining, and testing large systems.

The benefits of acyclic dependencies are enormous. The average time to link an indi-
vidual test driver for an acyclic design with tree-like dependencies is proportional to
the log of the number of components, rather than to the number of components itself,
as is the case for cyclic designs.
190 Physical Hierarchy Chapter 4

Number of
components Units of time
on this level needed to link Level

1 L

. . :.. : ....... ::.: ... : .... :. . ....... :... : .. ::": .. ":.: ...::: ..

··.cOrnponentseadl with a . . . ..
Hm\1,(:,hm[:n:':':iUiH2 ".· • '• ,.i.·. . . .·. .·.·. . . . i.·.·....·. i • · ;~iI'!} . • }\ • •. • i7~~~.')IJ..q~e· .cp §tqf7 lunits~
1
""":

7 3

3 2

1 1

Let L be the number of levels in the system (depth of the binary tree).
Let N = 2L - 1 be the number of components in the system.
CCDBalanced (N) L ( numberof ) ( link-time cost of )
Binary - S components • testing a component
Tree i=1 on level i on level i

L
- S 2L-i
• (2 i - 1)
i=1
L L
- S 2L S 2L-i
;=1 ;=1
L L
- 2L • S1 Si-1
i-I i=1

- 2L • L (2L_ 1)

_ 2L • (L - 1) + 1 Useful for comparison with a binary

{
dependency tree of integral height L.

- (N + 1) • (log2(N + 1) - 1) + 1

Useful for comparison with theoretical

- (N + 1) • log2(N + 1) - N { binary tree of arbitrary positive size N.

= O(N • 10g(N) { Asymptotic link-time cost.

Figure 4 .. 22: Computing Link-Time Cost for a Binary Tree of Dependencies

Section 4.12 Cumulative Component Dependency 191

Let N be the number of components in the system.

CCDcyclically (N) (N + 1) • (log2(N + 1) - 1) + 1

Dependent
Graph

Figure 4-23 compares link-time costs associated with testing cyclic and hierarchical
systems with N = 1, 3, 7, and 15 components. The number shown corresponding to
each component position in the dependency graph indicates the link cost associated
with incrementally testing that component. The CCD for each system is calculated
and shown at the bottom of its dependency graph. The CCD for each tree-like system
is calculated in two ways: once level by level and once using the equation derived in
Figure 4-22

N=3 N=7 N= 15

cyclic
dependency
structure

CCDCyclically (N) 3-3 =9 7-7 =49 IS-IS =225

Dependent
Graph

N=1 N=3 N=7 N= 15

tree-like
dependency
structure

CCDBalanced (N) I-I = 1 2 -I + 1- 3 =5 4 -I + 2 - 3 + 1- 7 =17 8 -I + 4 - 3 + 2 - 7 + 1- 15 =49

Binary 21_ 0 + 1 =1- 22 -1 + 1 =5 23 .2+ 1 =17 24 .3+ 1 =49
Tree
192 Physical Hierarchy t:hapter 4

Figure 4-23: Relative Link Costs Associated with Incremental Testing

Suppose that you are developing a system that has 63 components, each with its own
test driver. In a cyclic design, each component would take 63 seconds to relink in
order to test. Compare this to a hierarchical design (analyzed in Figure 4-24), in
which fully half of the components can be linked in 1 CPU second, a quarter in 3 CPU
seconds, an eighth in 7 CPU seconds,. and so on. Only one of the 63 components takes
the full 63 CPU seconds to link in order to test it. The total cost of linking all 63 test
drivers is calculated in two ways in Figure 4-24 to be 321 CPU seconds (5.35 CPU
minutes). Compare this with the 63 2 = 3,969 CPU seconds (1.1 CPU hours) it would
take to link all 63 test drivers to a cyclically dependent system.

Number of Cost to link • Link cost for

Level components a component all components
number on this level on this level on this level

1 32 • 1 - 32
2 16 • 3 - 48
3 8 • 7 - 56
4 4 • 15 -- 60
5 2 • 31 - 62
6 1 • 63 - 63
Total -- 321

CCDBalanced (63) = (63 + 1) • (10g2(63 + 1) - 1) + 1

Binary
Tree

64 • 5 +1

= 321

Figure 4-24: Link Cost for Balanced Binary Tree Hierarchy, N = 63

If the number of components were even larger, say 1,023 components, then the aver-
age cost of linking a component in a tree-like design would be two orders of magni-
tude less than for a cyclic design (9 versus 1,023 CPU seconds per component on
average). We can use the equation derived in Figure 4-22 to predict the CCO of this
Section 4.13 Physical Design Quality 193

system. The total link time alone for building component regression tests on a system
with 1,023 components could range from 1,024 - 9 + 1 = 9,217 CPU seconds (just
over 2.5 hours) for the hierarchically designed system to 1,023 -1,023 = 1,046,529
CPU seconds (over 12 days) for the cyclically dependent system.

It is unlikely that a single project would grow to 1,023 components without being
further partitioned into what we call packages. The importance of ensuring acyclic
dependencies among packages is even greater than that for individual components
(see Section 7.3).

CCD is also a predictor of the cumulative disk space requirements for incremental
regression testing. Disk space can become an important consideration when incremen-
tally testing a large system concurrently. The size of each independent executable test
programs on disk will be roughly proportional to the number of components to which
the test driver must statically link. Consequently, cyclically interdependent systems
can require significantly more disk space than -do hierarchical designs.

To summarize: our goal is to be able to build a test driver for each component that
links with the component to be tested and only the (few) components on which that
component depends. CCD is a metric that quantifies the coupling of a system in terms
of the total link-time cost associated with testing each component incrementally.
Cyclically dependent components exhibit quadratic behavior in terms of the link time
and disk space required in order to test them incrementally. In contrast, forming an
acyclic (tree-like) hierarchy of component dependencies reduces the link cost of
incremental component testing dramatically.

4.13 Physical Design Quality

In this section we characterize what makes a design maintainable in terms of its physical
dependencies. We continue to discuss CCD and how it is used to indicate the overall
maintainability of a subsystem. We also show how to use CCD to measure incremental
improvements in physical design qUality.

Imagine joining a company that is developing a very large system. You are handed a
subsystem of about 150,000 lines of C++ code and you are asked to understand what
it does and make suggestions as to how to improve it. Upon examination, you find that
the components (for the most part) are consistent with the rules and guidelines set
forth in Chapters 2 and 3. You then discover that most of the components in the sys-
194 Physical Hierarchy Chapter 4

tern depend (either directly or indirectly) on most of the other components. What do
you do? Unfortunately there is no happy ending to this story. The best anyone can do
may be to try to fit the entire design into his or her head, and that may take months.

Had the same subsystem been designed with an eye toward minimizing CCD, most-
if not all-cyclic dependencies would have been eliminated. It would be possible to
study pieces of the subsystem in isolation, to test, verify, tune, and even replace them,
without having to involve the entire subsystem either mentally or physically. In other
words, actively reducing the intercomponent dependencies, as quantified by CCD,
improves understandability and therefore maintainability.

Comprehension is one of several hard-to-quantify yet very real advantages of

minimizing intercomponent dependencies; selective reuse is another. Consider the
architecture of the subsystem illustrated in Figure 4-25. This system consists of seven
components, each of which depends either directly or indirectly on every other
component in the system. Each of the components can be tested directly, but none of
them can be tested in isolation or reused independently of the rest. Because each inde-
pendent test driver is forced to link with the entire system, the amount of disk space
required just to store these independent drivers will be quadratic as well.

CCD=49

Figure 4-25: Cyclically Dependent Subsystem Architecture of Size 7

Assume now that the cyclic dependencies in the design of Figure 4-25 are removed,
making it levelizable. Although levelizability is highly desirable, some levelizable
architectures are more maintainable and reusable than others. Consider the design
hierarchies shown in Figure 4-26. Each hierarchy contains seven components, and
each is levelizable. Figure 4-26a shows one extreme version of levelization. Designs
of this nature are termed vertical. Each component in this system depends on all of the
components at lower levels. Vertical subsystems exhibit a high degree of coupling,
Section 4.13 Physical Design Quality 195

which inhibits independent reuse. Reusing a randomly chosen component in a vertical

system of size N will on average result in having to link to (N - 1)/2 additional com-
ponents. The average disk space required to hold incremental test driver programs
will be correspondingly large.

Level 7:
Level 6:
LevelS:
Level 4:
Level 3:
Level 2:
Levell: .11_._1I1ll
CCD=28 CCD = 17 CCD=7
(a) Vertical (b) Tree (c) Horizontal

Figure 4-26: CCD for Various Component Hierarchies of Size 7

Vertical systems are highly inflexible with respect to both testing and reuse. There is
only a single order in which to test purely vertical systems, and that order is entirely
determined by its levelization. Developing a vertical subsystem is also relatively
expensive in terms of link times. The total link cost (CCD) of 28 units for this system
is more than half of the 49 units for the cyclically dependent subsystem shown in Fig-
ure 4-25. Furthermore, a vertical subsystem will be relatively difficult to partition into
parallel development efforts, spread across multiple developers. A vertical subsystem
is, however, acyclic and therefore qualitatively easier to maintain than if it were
cyclic.

Figure 4-26b shows a design hierarchy in the form of a binary tree. As we know, over
half of the components in this design contribute only a single unit each to the CCD.
Designs will not be perfect binary trees, but the CCD of a binary tree serves as a good
benchmark against which to compare many typical applications. Tree-like designs,
with their lower degree of coupling, are much more flexible and suited to reuse than
vertical designs. At each level there are typically several subsystems that can be tested
196 Physical Hierarchy Chapter 4

and possibly reused independently of the rest of the system. The disk space require-
ment for holding most of the incremental test driver programs will be relatively low.

By making the dependency graph flatter rather than taller, we increase flexibility. The
flatter the design, the greater the potential for independent reuse. Flattening the
dependencies also helps to decrease the time needed for understanding and mainte-
nance. The flatter the design, the more likely a bug can be tracked to a single, isolated
component or a small independent subsystem, and therefore the less disk space will
be required by the driver executable to exercise the defect.

Figure 4-26c shows the other end of the levelization spectrum. This type of design is
characterized as horizontal because all of the components are entirely independent
and decoupled from one another. Components belonging to purely horizontal sub-
systems may be tested in any order and reused in any combination desired. The disk
space requirement for every incremental test driver program will be quite low. Such
dependency characteristics are typical in reusable component libraries but atypical of
subsystems in generaL

We can make some objective, quantitative statements about the relative maintainability
and reusability (but not necessarily the "goodness") of a design of a given size based
on its CCD. Design dependencies form a continuum that ranges from cyclic to verti-
cal to tree-like to horizontal. Even in the presence of cycles, every design can be
assigned a CCD. All other things being equal, the lower the CCD, the less expensive
(in terms of link time and disk space) the system will be to develop and maintain.

There is yet another reason to strive for a hierarchical system with a minimal CeDe
Requirements are rarely cast in stone and may change during the development of a
project. By distributing the implementation throughout a hierarchy of components,
the design becomes more resilient to change. The more horizontal an architecture, the
less it is likely that any changes in specification will affect the overall system. This
expected cost due to changes in specification is directly related to the average compo-
nent dependency (ACD) in the system.
Section 4.13 Physical Design Quality 197

DEFINITION: Average component dependency (ACD) is defined as

the ratio of the CCD of a subsystem to the number of components N
in the subsystem:
CCD(subsystem)
ACD(subsystem) =
Nsubsystem

For example, changing the specification of a single component in a fully horizontal

subsystem causes only one component to change. For a tree-like architecture with N
components, up to roughly 10g(N) components may need to change on average. For a
vertical structure, we might expect to revisit as many as (N + 1)/2 components as a
result of having to modify the interface to just one. Finally, for a fully cyclically
dependent design, all N components could be affected by a single change.

"
.. . . . . 1l.•·:..•. •".:r..•·.•..:: . :c..••.·:•.. : I.··.•e.•.·•. .• I
I
"0:::" . . . . . . :.

.
I. •. •. •.D
·. ·.• ·•. ·•·. •. 1..•·•. ··•.:Hi.>
n.·.··
.••. •.•·.•.•.

The primary purpose of CCD is to quantify the change in overall

coupling resulting from a minor perturbation to a given architecture.

As an illustration of reducing CCD, consider the two systems with similar depen-
dency structure shown in Figure 4-27. Design A has a cyclic dependency between two
of its components. Testing either one of these components requires linking to both of
them, along with all of the components on which either one of them depends; this
gives each of them an individual component dependency of 7. Notice also that at the
right of Design A, a portion of the hierarchy is purely vertical.
198 Physical Hierarchy Chapter 4

Cyclic
Dependency

N= 11, CCD = 39 N= 11, CCD = 32

(a) Original Design A (b) Modified Design B

Figure 4-27: Dependency Grapbs for Two Alternative Designs of a Subsystem

Several techniques for reducing link-time dependencies are presented in detail in

Chapter 5. To improve this design we would first like to try to break the cyclic depen-
dency and then examine the vertical section to see if it can be made less serial. In this
case, it may be possible to break the cycle merely by escalating some code to a higher
level and/or factoring out a shared resource. As for the vertical section, it may be that
one or more components in the chain can be removed and made into leaf components,
independent of the rest. The result of making these modifications is Design B, shown
in Figure 4-27b. The CCD of 39 for our original Design A is much lower than the CCD
of 121 for a fully interdependent design. Yet we were still able to reduce the CCD in
this nearly hierarchical system from 39 to 32-an improvement of about 18 percent.

CCD is an objective metric that characterizes the physical coupling within a system.
CCD can flag subsystems with unusually high incremental development and mainte-
nance costs. For example, a vertical chain is the levelizable configuration with the
highest CCD: N(N + 1)/2. Therefore a CCD of greater than N(N + 1)/2 implies that at
least one cyclic dependency exists. However, CCD is not (by itself) a measure of the
quality of a subsystem.

We can conveniently use the alternate equation derived in Figure 4-22 to determine
the CCD for a (theoretical) binary-tree-like architecture of the same size as those
shown in Figure 4-27. Figure 4-28 demonstrates that a binary-tree-like architecture
with 11 components has a CCD of 32.02, which is comparable with that of Design B.
Section 4.13 Physical Design Quality 199

CCDBalanced (N) = (N + 1) -Iog2(N + 1) - N

Binary
Tree

CCDBalanced (11) = (11 + 1) - Iog 2(11 + 1) - 11

Binary
Tree

= 12 -Iog2(12) - 11

= 32.02
Figure 4-28: Computing the CCD of a Theoretical Balanced Tree of Size 11

DEFINITION: Normalized cumulative component dependency

(NCCD) is defined as the ratio of the CCD of a subsystem containing
N components to the CCD of a tree-like system of the same size.

CCD(subsystem)
NCCD(subsystem) =
CC~alanced(Nsubsystem)
Binary
Tree

The NCCD of a system can be used to characterize the degree of physical coupling
within the system relative to a theoretical binary-dependency tree of the same size.
Referring back to Figure 4-27, the NCCD of Design B was 32/32.02 = 1.00 as com-
pared with an NCCD of 39/32.02 = 1.21 for Design A (and 121/32.02 = 3.78 for the
completely interdependent implementation).

An NCCD of less than 1.0 can be thought of as more "horizontal" or loosely coupled;
such a system probably employs little reuse. An NCCD of greater than 1.0 can be
thought of as more "vertical" and/or tightly coupled; such a system may be making
extensive reuse of components. An NCCD substantially greater than 1.0 indicates that
there may be significant cyclic physical coupling within the system.

The degree of maintainability in terms of the CCD that we are able to achieve depends
on the nature of the subsystem. We will not always achieve perfect tree-like maintain-
ability. For horizontal component libraries, we would expect a much lower CCD. The
200 Physical Hierarchy Chapter 1
CCD will be higher for highly interconnected topologies that employ reuse heavily,
such as the window system shown in Figure 2-8 of Section 2.5.

NeeD is not a measure of the relative quality of a system. NCCD is simply a tool for
characterizing the degree of coupling within a subsystem. Increasing the number of
components in a system could artificially reduce the NCCD. One way to do this is to
eliminate completely valid reuse; this would likely not be an improvement.

Figure 4-29 shows two designs with equivalent functionality. Design B is 50 percent
larger than A with a 25 percent larger CCD. On the other hand Design A, through
reuse, exhibits more physical coupling for its size than does Design B. Nonetheless,
Design A may very well be the better engineered and more maintainable design.

SIZE = 4 SIZE = 6
CCD= 8 CCD = 10
NCCD = 1.05 NCeD = 0.73

(a) Design A (b) Design B

Figure 4-29: lliustrating the Effects of Redundancy

Minimizing CCD for a given set of components is a design goal.

Reducing the CCD in a system of a given size is almost always desirable. Reducing
the size (number of components) of a system is also desirable but not at the cost of
introducing cyclic dependencies, inappropriately merging components, or creating
Section 4.14 Summary 201

unmanageably large translation units. When increasing the number of components in

a system actually reduces the CCD, chances are that the overall quality of the design
has been improved.

In conclusion, the CCD metric has been introduced to identify explicitly the kind of
dependencies we would like to minimize. NCCD gives us a quantitative way of char-
acterizing the physical dependencies of a subsystem as horizontal, tree-like, vertical,
or cyclic. The precise numerical value of the CCD (or the NCCD) for a given system
is not important. What is important is actively designing systems to keep the CCD for
each subsystem from becoming larger than necessary.

4.14 Summary

High-quality, complex subsystems are composed of many components layered on top

of each other to form an acyclic physical hierarchy. Thorough testing at the system
level is not just expensive, but highly infeasible-if not impossible-particularly for
"good" interfaces.

A "good" interface encapsulates the complexity of the implementation behind a simple

facade that is easy to use. At the same time, it makes our ability to test the implemen-
tation through this interface exceedingly difficult.

Much of the testing strategy in this chapter is motivated by the success of Design For
Testability (DFT) over a decade ago. But, unlike real-world objects, instances of
classes defined within a software system are no different from instances of the same
classes defined outside that system. We can exploit this fact to verify portions of the
design hierarchy in isolation, thereby reducing part of the risk of integration.

Isolation testing is a cost-effective way of ensuring reliability in complex, low-level

components. By pushing the testing to the lowest possible level in the design hierarchy,
we ensure that if the component or subsystem is enhanced, ported, or reused in another
system, it will continue to adhere to its specified behavior independently of its clients.

Level numbers characterize components in terms of their physical dependencies on

other components within a subsystem. Furthermore, level numbers provide an order
in which systems with acyclic component dependency graphs can be tested effec-
tively. Subsystems whose component. dependencies form a directed acyclic graph
(DAG) are said to be levelizable. A levelized component dependency diagram makes
202 Physical Hierarchy Chapter 4

the physical structure of a system easier to understand, and consequently easier to

maintain.

Hierarchical testing refers to testing components at each level of the physical hierarchy.
Each lower-level component should provide a well-defined interface and implement
predictable functionality that can be tested, verified, and reused independently of
components at higher levels.

Incremental testing refers to having individual drivers test only the functionality actu-
ally implemented within the component under test; functionality implemented at
lower levels of the physical hierarchy is presumed at this point to be internally correct.
Consequently, incremental tests mirror the complexity of the implementation of the
component under test and not that of the hierarchy of components upon which this
component depends. Incremental testing is a form of white-box testing, which relies
on knowing the implementation of the component in order to improve reliability.
Black-box testing derives from requirements and specifications, and is independent of
implementation. These two forms of testing are complementary, and both contribute
to ensuring overall quality.

Testability is a design goal. Cyclic physical dependencies inhibit testing, understand-

ing, and reuse. Cumulative component dependency (CCD) provides a crude numerical
measure of the overall link-time cost associated with incrementally testing a given
subsystem. More generally, CCD is an indicator of the relative maintainability of a
given design.

Cyclically dependent designs are not levelizable. Such systems are known to be diffi-
cult to maintain and have a correspondingly high CCD. Among designs that are level-
izable, the more horizontal the hierarchy, the lower the CCD. Flattening physical
dependencies helps to decrease the time needed for understanding, development, and
maintenance, while improving the flexibility, testability, and reusability of a system.
NCCD (normalized CCD) helps to categorize the physical structure of arbitrary
designs as cyclic, vertical, tree-like, or horizontal.
 Levelization

Link-time dependencies within a system (as quantified by CCD) playa central role in
establishing the overall physical quality of a system. More conventional aspects of
quality, such as understandability, maintainability, testability, and reusability, are all
closely tied to the quality of the physical design. If not carefully prevented, cyclic
physical dependencies will rob a system of this quality, leaving it inflexible and diffi-
cult to manage.

Even revisable designs can be unnecessarily costly to maintain and enhance. Forced
dependency on large, low-level subsystems can pose a significant development burden
on higher-level subsystems. Minimizing the impact of such dependencies contributes
to the physical quality of the system.

In this chapter, we explore several techniques for eliminating cyclic or otherwise

excessive link-time dependencies. Escalation and demotion are related techniques that
move a cyclicly dependent portion of the design to a different level in the physical hier-
archy. Opaque pointers and dumb data are used to remove the physical implications of
conceptual dependency. Redundancy and callbacks are yet two other techniques we
discuss to prevent unwanted physical dependencies. Finally, a manager class is pre-
sented along with two general techniques (factoring and escalating encapsulation) to
help create efficient, encapsulating hierarchies of testable and reusable components.

Throughout this chapter we use many examples taken from several application
domains to illustrate these techniques in a variety of contexts. Occasionally we present
a substantial body of source code to make the example concrete for reference purposes.
204 Levelization Chapter 5

5.1 Some Causes of Cyclic Physical Dependencies

In this section we look at three ways in which cyclic physical dependencies can occur
in practice. To demonstrate the breadth of this problem, we preset;lt and discuss each of
these examples in a separate subsection without attempting to resolve them. These spe-
cific problems and many others will be solved as appropriate techniques are presented
throughout the remainder of this chapter.

5.1.1 Enhancement

Initial designs are usually carefully planned and often levelizable. In time, the unan-
ticipated needs of clients can evoke less-well-thought-out enhancements that induce
unwanted cyclic dependencies. For example, we sometimes find we have similar
objects that, for one reason or another (e.g., performance), coexist in a system but that
contain essentially the same information.

Figure 5-1 shows a simple but illustrative example consisting of two classes, each rep-
resenting a kind of box. A Rectangl e is defined by two points that determine its
lower-left and upper-right corners. A Wi ndow is defined by a center point, a width, and
a height. These objects have distinct performance characteristics but contain the same
logical information.

II rectangle.h II window.h
#ifndef INCLUDED_RECTANGLE #ifndef INCLUDED WINDOW
#define INCLUDED RECTANGLE #define INCLUDED_WINDOW

class Rectangle { class Window {

I I ... I I ...
public: public:
Rectangle(int xl. Window(int xCenter.
int yl. int yCenter,
int x2, int width,
int y2); int height);

I I ... I I ...
int lowerLeftX() const; int width() canst;
II I I ...
}; };

#endif #endif

Figure 5·1: Two Representations of a Box

Section 5.1.1 Enhancement 205

Each of these objects will be used to facilitate the rendering of very large designs
interactively on a graphics terminal; draw speed will be critical. For performance rea-
sons, we do not even consider employing virtual functions, and most of the functions
are declared i n 1 i n e.

Allowing two components to "know" about each other via Iii ncl ude
directives implies cyclic physical dependency.

It turns out that clients will occasionally need to be able to convert between these two
types of boxes, perhaps to obtain the performance characteristics of the other. This is
one way in which good designs can sometimes start to deteriorate.

Consider the "solution" set forth in Figure 5-2. We have added to each class a con-
structor that takes as its only argument a con s t reference to the other class. We can
now pass a Wi ndow object to a function requiring a Rectangl e and vice versa, the con-
version being performed implicitly. How does that sound to you?

If it sounded good to you, you are not alone. But it is not a good solution. For one
thing, any speed benefit that might be realized could be lost by having to construct a
temporary object of the other type on entry to a function. Since the conversion is
implicit and automatic, your clients may not even realize that the extra temporary is
being created (and will blame you for your "slow" class).

Much more importantly, we have introduced a cyclic physical dependency between the
header files of two previously independent components. Each of these components
now must "know" about the other. It is no longer possible to compile, link, test, or use
either one of these components without the other. Most clients will not be concerned
about the subtle differences in performance characteristics between these classes and
would opt to iIse either one, but rarely both. This unlevelizable enhancement forces
them to take both.
206 Levelization Chapter 5

II rectangle.h II window.h
#ifndef INCLUDED_RECTANGLE #ifndef INCLUDED_WINDOW
#define INCLUDED_RECTANGLE #define INCLUDED_WINDOW

#ifndef INCLUDED_WINDOW #ifndef INCLUDED_RECTANGLE

#include "window.h" #include "rectangle.h"
tFendif 1Fendif

class Rectangle { class Window

I I ... I I ...
public: public:
I I ... I I ...
Rectangle(const Window& w); Window(const Rectangle& r);
I I ... II ...
}; };

i n1 i
ne II
Rectangle::Rectangle(const Window& w)
{
I I ... i n 1 i ne
} Window::Window(const Rectangle& w)
{
II 1/
}

#endif #endif

rectangle.h window.h

rectangle.c window.c

rectangle window

Figure 5-2: Two Mutually Dependent Components

We can move the preprocessor tf inc 1 ude directives from the . h files to the . c files (as
shown in Figure 5-3), but this does not eliminate the physical coupling. Both compo-
nents still depend on each other at compile time, and each will potentially depend on
the other at link time. We need to do something a bit more radical.
Section 5.1.1 Enhancement 207

II rectangle.h II window.h
#ifndef INCLUDED_RECTANGLE #ifndef INCLUDED~WINDOW
#define INCLUDED_RECTANGLE #define INCLUDED_WINDOW

class Window; class Rectangle;

class Rectangle { class Window {

I I ... I I ...
public: public:
I I ... I I ...
Rectangle(const Window& w); Window(const Rectangle& r);
I I ... II
}; };

#endif #endif

rectangle.c window.c

rectangle window

Figure 5-3: Two Components Still Mutually Dependent

DEFINITION: A subsystem is levelizable if it compiles and the graph

implied by the include directives of the individual components
(including the . c files) is acyclic.

Suppose a subsystem consists of a collection of components that follow all of the

major design rules set forth in Chapters 2 and 3. We can make use of the above alter-
native definition of levelizable to help us avoid enhancements that cause components
to become physically coupled. Somehow we must find a way to allow a client to con-
vert between rectangles and windows without requiring each component to include
the other.
208 Levelization Chapter 5

5.1.2 Convenience

Often, in an effort to make a system usable, developers are tempted to create designs
that are not structurally sound. As a second, more involved example of this recurring
theme, consider a graphical shape editor whose design is depicted abstractly in Figure
5-4. The Shape class is abstract and defines a protocol that all concrete shapes must
implement. Every shape has a location that we will assume for now must be manipu-
lated as quickly as possible (i.e., via inline functions). Since some of the functionality
in the Shape class is already implemented, Shape serves not only to define a common
interface, but also to factor the common part of the implementation. 1

1 Section 6.4.1 describes how we could reduce compile.:.time coupling between consumers and sup-
pliers of the Shap e interlace if we relaxed the speed requirement for the m0 veT 0 function.
Section 5.1.2 Convenience 209

Figure 5-4: Unlevelizable Design of a Shape Editor

The Shap e class could potentially define a large number of pure virtual functions. A
sparse representation of the header file for the shape component is presented in Figure
5-5. Clients of the Shape class will need to be able to create actual shapes, but they
will not need to interact with the derived class interfaces directly. In order to insulate
clients of Shap e from concrete classes derived from Shap e, the ability to create spe-
cific kinds of Shape is incorporated directly into Shape's interface.
210 Levelization ChapterS

II shape.h
#ifndef INCLUDED_SHAPE
#define INCLUDED_SHAPE

class Screen;

class Shape {
int d_xCoord;
int d-yCoord;

protected:
Shape(int x, int y);
Shape(const Shape& shape);
Shape& operator=(const Shape& shape);

public:
static Shape *create(const char *typeName);
virtual -Shape();
I I ...
v0 i d m0 veT a ( i nt x, i nt y) { d_x = x; d-y = y; }
I I ...
virtual Shape *clone() const = 0;
virtual void draw(Screen *s) canst - 0;
I I ...
};

#endif

Figure 5-5: Elided. h File for Component shape

To make it easy to add new shapes by name, the Shap e class implements the static
member function create. This method takes the type name of the Shape (as a canst
cha r *) and returns a pointer to a dynamically allocated, newly constructed Shape of
the appropriate concrete type derived from Shap e. 2 If no shape corresponding to that
type name exists, the function returns o. The entire . c file for the s hap e component is
presented in Figure 5-6.

2 Returning a pointer to a dynamically allocated object is error prone because it leaves the responsi-
bility of deallocation with the client. Failing to catch an exception can easily result in a memory leak.
Handle classes (as discussed in Section 6.5.3) can be used to reduce the potential for memory leaks.
Section 5.1.2 Convenience 211

II shape.c
#include "shape.h"
#include "circle.h"
#include "square.h"
#include "triangle.h"
#include "screen.h"
#include "string.hl! II strcmpC)

Shape: :ShapeCint x, int y)

: d_xCoordCx)
, d-yCoordCy)
{}

Shape::ShapeCconst Shape& s)
: d_xCoord(s.d_xCoord)
, d-yCoordCs.d-yCoord)
{}

Shape& Shape::operator=(const shape& s)

{
d_xCoord = s.d_xCoord;
d-yCoord = s.d-yCoord;
return *this:
}

Shape: :---Shape() {}

Shape *Shape::create(const char *s)

{
if C0 == s t r cmp ( S, Ci r c 1 e" )) {
II

return new Circle(x, y, 1); II unit radius

}
e 1 s e i f (0 == s t r cmp Cs, " Squa r e")) {
return new Square(x, y. 1); II unit side
}
else if (0 == strcmp(s, "Triangle")) {
return new Triangle(x, y, 1, 1, I); II unit side
}
else {
return 0; II unknown shape
}
}

Figure 5-6: Entire. c File for Component shape

The Ed ito r class itself is layered upon a number of custom types (E 1, ..., En) used
solely in the implementation of Ed ito r. Each of these types uses Sh a pe in its interface
in order to perform various abstract operations on shapes (e.g., move To, sea 1e, draw,
and so on). Only one of the implementation components, el, which implements the add
212 Levelization ChapterS

command, needs to be able to create a shape from a type name. The rest of these com-
ponents can use Shape's virtual functions to access a particular Shape's functionality,
and do not need to depend on any concrete Shape directly. Does this sound reasonable?

Although this design may seem appealing from a usability standpoint, it has a design
flaw that makes it quite a bit more expensive to maintain than it need be. The ere ~•. ~
ate member function of S hap e uses a constructor of each of the classes derived from
Shape, which forces a mutual dependency between Shape and all classes derived from
Shape. It is therefore not possible to test a specific kind of Shape independently of all
the rest, significantly increasing the link time and disk space required during incre-
mental testing. The shape subsystem, which is otherwise horizontal and therefore
highly reusable, is turned into an all-or-nothing proposition.

Adding a new kind of shape to this subsystem requires modifying the Shape base
class, which could produce errors in functionality pertaining to the other indepen-
dently derived classes. The high degree of coupling brought on by having a base class
"know" about its derived classes implies a considerable increase in maintenance cost
and a considerable loss of flexibility and reuse.

The maintenance disadvantage worsens when we consider that only component el

needs to create each of the Edi tor's concrete shapes and therefore only el needs to
depend on all of the individual concrete shape components. Components e2, e3, ... ,
en merely use these shapes via the virtual functions of the abstract base class Shap e. If
we can assume that the functionality of each shape is working properly, then we need
test only that each editor subsystem component is interacting with the Shap e protocol
properly. There could be dozens or even hundreds of different kinds of shapes, and it
is neither necessary nor practical to test each editor subsystem component with every
type of shape all the time. Yet, because of the coupling in the shape subsystem, we are
forced to link to all shapes whenever incrementally testing anyone of the editor
implementation components.

In order to improve the maintainability of this system, we need to find a way to

repackage the shape subsystem so that it becomes acyclic and therefore levelizable.
section 5.1.3 Intrinsic Interdependency 213

5.1.3 Intrinsic Interdependency

Interconnected networks of objects present an engineering challenge for software sys-

tem architects. The high degree of inherent coupling, particularly in the interface,
makes achieving levelization less obvious and intuitive. In this final introductory
example we examine the difficulty in implementing a graph, which is among the most
basic of object networks.

Inherent coupling in the interface of related abstractions makes them

more resistant to hierarchical decomposition.

Consider the graph shown in Figure 5-7. A graph consists of a collection of nodes and
edges. The nodes within this graph are connected by directed edges. In general, the
edges in the graph will form cycles. 3 Each node consists of some data and some infor-
mation about how the node is incorporated into the graph. In this example the node's
data is no more than a name. The connectivity is represented simply as a list of edges
to or from that node.

6
Susan ~
- - - - - - - I.. Franklin

Mindy --------1~~ Rick. -----------~~ Cathy

5 3

Figure 5-7: Simple Graph Consisting of Nodes and Edges

Figure 5-8 illustrates the minimal functionality associated with the node component.
Given a Node, it is possible to ask for its name, find out the number of edges connected

3 Note: these are cycles among instances, not classes.

214 Levelization ChapterS

to it, and iterate over these edges by supplying integer indices between 0 and N-l,
where N is the current value returned by Node: : n umEdges ( ).4

II node.h
#ifndef INCLUDED_NODE
#define INCLUDED_NODE
class Edge;
class Node {
I I ...
Node(const Node&); II not implemented
Node& operator-(const Node&): II not implemented
public:
Node(const char *name);
,....Node() ;
canst char *nameC) canst;
int numEdges() const;
Edge& edge(int index) canst;
};
#endif
Figure 5-8: Public Interface of node Component

II edge.h
#ifndef INCLUDED_EDGE
#define INCLUDED_EDGE
class Node;
class Edge {
I I ...
Edge(const Edge&); II not implemented
Edge& operator=(const Edge&); II not implemented
public:
EdgeCNode *from, Node *to, double weight);
-Edge ( ) ;
Node& fromC) const;
Node& toC) const;
double weight() canst;
};
#endif
Figure 5-9: Public Interface for an edge Component

4 It
is a subtle point that supplying an integer index for iteration suggests that the underlying imple-
mentation is likely to be an array of some kind and not a linked list of edges. A naive linked-list
implementation would result in quadratic runtime behavior during iteration.
Section 5.2 Escalation 215

An Edge in this system is used to connect rtodes. Like nodes, edges also contain both
local and network-related functionality. The network-independent infonnation associ-
ated with the Edge in this example is just its weight, and the connectivity information
is just the two Nod e objects to which the Ed g e is connected.

Initially we are faced with the unappealing design illustrated in Figure 5-10. Node
uses Edge in its interface and vice versa. As it stands, it seems as though class Node
and class Edge must be mutually dependent-otherwise how could a client possibly
traverse the graph? Furthermore, there is the question of who owns the memory for
these objects and who is authorized to bring instances of Node and/or Edge into and
out of existence.

node edge

Figure 5-10: Cyclicly Dependent node and edge Components

Recall from Section 3.6 that friendship does not introduce physical dependencies by
itself, but in order to preserve encapSUlation it can indirectly cause physical coupling
to occur. In order to avoid the breach of encapsulation and lack of modularity associ-
ated with long-distance friendships, it may be necessary to group severallevelizable
classes within a single component (as explained at the end of Section 5.9). A common
example of this kind of coupling can be seen in virtually every container component
that supplies an iterator. Invariably the iterator will be a friend of the container and
therefore defined within the same component.

The above are but a few examples of the kinds of cyclic coupling that commonly arise
in practice. The remainder of this chapter is devoted to developing various techniques
and transformations for untangling designs that might otherwise seem to defy an acyclic
physical implementation.

5.2 Escalation

Let's now return to the example involving the two cyclicly dependent components
(shown in Figure 5-1): rectangl e and wi ndow. Suppose that instead of having
rectangl e and wi ndow "know" about each other, we decide arbitrarily that rectangles
216 Levelization Chapter 5

are more basic than windows. We can move both conversions into class Wi ndow.
Win d ow now "uses" Re eta n 9 1 e but not vice versa, as is illustrated in Figure 5-11.

window

Level 2:

II window.h
#ifndef INCLUDED_WINDOW
#define INCLUDED_WINDOW
Levell:
#ifndef INCLUDED_RECTANGLE
#include "rectangle.h"
rectangle #endif

class Window {
I I ...
public:
I I ...
Window(const Rectangle& r);
I I ...
operator Rectangle() const;
I I ...
II rectangle.h };
#ifndef INCLUDED_RECTANGLE
#define INCLUDED_RECTANGLE II

class Rectangle { inline

I I ... Window: :aperator Rectangle() canst
public: {
I I ... I I ...
}; }

#endif ifendif

Figure 5-11: wi ndow Dominates rectangl e

Section 5.2 Escalation 217

This solution requires that we change our point of view somewhat, because the
Rectangl e and Wi ndow classes are no longer symmetric. Rectangl e lives at levell,
but Win d ow is now defined at level 2. If we want any old box we can reuse Re eta n91 e
and not worry about Win d ow or conversions between the classes. If we need a Win dow,
however, we will have to take Rectangl e also.

DEFINITION: A component y dominates a component x if y is at a

higher level than x and y depends physically on x.

Dominance is a property among components that is roughly comparable to the prop-

erty with the same name among virtual base classes within a single derived object. 5
We introduce the concept of dominance among components now and mention that
Figure 5-11 illustrates an example where component wi ndow dominates component
rectangl e. We refer to this definition of dominance in later sections.

As Figure 5-12 illustrates, component u dominates both components rand s.

Although component v is at a higher level than either component r or component s, it
dominates only component t. Component w dominates all five components r, s, t, U,
and v.

Level 3:

Level 2:

Levell:

Figure 5-12: lliustration of Dominance Property for Components

The significance of dominance is that it can provide additional information beyond

simple level numbers. For example, adding a dependency from a higher-level com-

5 ellis, Section 10.1.1, pp. 204-205.

218 Levelization Chap~erS

ponent to a lower-level component (e.g., from u to t in Figure 5-12) never intro

duces a cyclic dependency or changes the level numbers (as shown in Figure 5-13a).

Level 5:

Level 4:

Level 3:

Level 2:

Levell:

(b) + '", .
~~

Figure 5-13: Adding a Dependency Can Cause a Change in Level Numbers

Adding a dependency between two components at the same level (e.g., from v to u in
Figure 5-12) also never introduces a cycle but does affect the level number as shown
in Figure 5-13b. Finally, it may even be possible to add a dependency from a lower-
level component to a higher-level one (e.g., from t to u in Figure 5-12 without intro-
ducing a cyclic dependency). Adding this dependency without introducing a cycle
will be possible if and only if component u does not already dominate component t.
Here, component u does not dominate component t and the result of adding the
dependency from t to u is shown in Figure 5-13c.

Of course we could have gone the other way and made Wi ndow the primitive object. In that
case rectangl e knows about wi ndow but not vice versa. This situation is depicted in Fig-
ure 5-14. Notice that in this example we have elected to move the If inc 1ude" win dow. h"
directive to the rectangl e. c file, which implies that the conversion routines will not be
inline.
Section 5.2 Escalation 219

Level 2:

Levell:

window
II rectangle.h
#ifndef INCLUDED_RECTANGLE
#define INCLUDED_RECTANGLE
class Window;

class Rectangle { II window.h

I I ... #ifndef INCLUDED_WINDOW
public: #define INCLUDED_WINDOW
I I ...
Rectangle(const Window& w): class Window {
I I ... // ...
operator Window() canst; public:
I I ... I I ...
}: };

#endif #endif

Figure 5-14: rectangl e Dominates wi ndow

Both solutions imply that only one component can be used independently of the other.
Either solution is an improvement over the original cyclicly dependent design, but we
can do still better. Many clients who use these components will need one or the other
but not both. Of those that do need to use both components, only some will need to
convert between them. To maximize independent reusability, we can avoid having
either component dominate the other by moving the cycle-inducing functionality to a
higher level-a technique referred to in this book as escalation.
220 Levelization Chapter 5

If peer components are cyclicly dependent, it may be possible to esca-

late the interdependent functionality from each of these components
to static members in a potentially new higher-level component that
depends on each of the original components.

In corporations, if two employees are not able to resolve a dispute, the common prac-
tice is to escalate the problem to a higher level. In the case of objects competing for
dominance, the same solution is often effective. We can create a utility class called
Box Uti 1 that knows about both the Re eta n91 e and Win dow classes and then place the
definition of this class in an entirely separate component, as shown in Figure 5-15.

Now clients interested in either Rectangl e class or Wi ndow class·are free to use either
class independently. If a single client happens to use both classes but does not need to
convert between them, so be it. If yet other clients require the conversion routines,
they are available. However, note that conversion between Rectangl e and Wi ndow,
which used to be implicit, must now be performed explicitly. (See Section 9.3.1 for
more on implicit conversions.)

Note that, in the previous example, we elected to use the keyword s t rue t instead of
c 1 ass when defining BoxUt i 1 to suggest that this type merely provides a scope for
public nested types and public static member functions. In this convention, all mem-
bers of a struct are public and hence there are no data members. Although creating
an instance of such a type is pointless, it does no real harm. We can reduce some
unnecessary clutter if we suppress our compulsion to declare the unimplemented
default constructor p r i va teo
Section 5.2 Escalation 221

boxutil

Level 2:

Levell:

rectangle window

I I boxuti 1. h
#ifndef INCLUDED BOXUTIL
#define INCLUDED BOXUTIL

class Rectangle;
class Window;

struct BoxUti 1 {
static Window toWindow(const Rectangle& r);
static Rectangle toRectangle(const Window& w);
};

#endif

II rectangle.h II window.h
#ifndef INCLUDED_RECTANGLE #ifndef INCLUDED_WINDOW
#define INCLUDED_RECTANGLE #define INCLUDED_WINDOW

class Rectangle { class Window {

I I ... I I ...
public: public:
I I ... I I ...
}; };

ffendif #endif

Figure 5-15: Neither rectangl e Nor wi ndow Dominates the Other

222 Levelization Chapter 5

Now let's consider again the physical coupling induced by the static create function,
defined in the base class of the shape hierarchy of Figure 5-4. Suppose we escalate
ere ate above the level of its derived classes by introducing a new utility class,
Shap eUti 1, whose sole purpose is to create shapes. This new class would be placed in
its own component and contain the ere ate function from the original Shap e class, as
shown in Figure 5-16.

/ / shapeuti 1. h
#ifndef INCLUDED_SHAPEUTIL
#define INCLUDED_SHAPEUTIL

class Shape;

struct ShapeUtil {
static Shape *create(const char *typeName);
}; .

#endif

Figure 5-16: Header File for New Component shapeuti 1

By adding a new component and escalating the Uses relationship to a higher level, we
have removed the cyclic dependencies among all components in the shape subsystem.
The levelized diagram for the new system is shown in Figure 5-17.

It is now possible for each concrete shape to be tested in isolation. Even the partial
implementation provided by class Shape can be tested modularly by deriving a con-
crete "stub" class from Shap e in the test driver for the s hap e component. Each of the
concrete shapes can now be reused independently of the rest in any combination. For
example, another system is now able to reuse ci rcl e. and square without having to
link: in t ria n9 1e.

It is now also possible to test each of E2, ... , En without having to link to every con-
crete shape. Since these components require only the shape base class interface, it may
be deemed sufficient to test the incremental value added by each of the editor compo-
nents e2, ... , en on only a representative sample of all available concrete shapes.

The advantage of this new design over the original is a reduction in coupling that will
translate directly into reduced development and maintenance costs while amplify-
ing the potential for reuse. It may be difficult to appreciate the importance of this
design approach when the number of implementation components in the editor, and,
Section 5.2 Escalation 223

particularly, the number of concrete shapes, is small. The real advantage is that this
new design scales up much better than the original as more editor commands and new
kinds of Shape are added.

shapeutil fully levelizable shape subsystem

Figure 5-17: Improved Design for Shape Editor

224 Levelization Chapter 5

As an objective, quantitative measure of the improvement ~hat levelization brings to

this design, let us consider four variants of the editor system. In the "scaled-down" "
version of this system, Figure 5-18a, both the editor and the number of shapes it
works on are small (three shapes and three editor-implementation components). The
numbers in the upper left comers of the component rectangles indicate the number of
components that must be linked in order to test that component incrementally.

At first glance, this new design may appear to be unnecessarily complicated, but in
fact it simplifies the job of both developer and client. Even with the additional compo-
nent in the new design, the coupling' associated with hierarchically testing the shape
subsystem as measured by CCD is reduced by a full 25 percent. The coupling associ-
ated with incrementally testing the editor subsystem is reduced by 17.4 percent, giving:
an overall reduction in CCD of 20.5 percent.

Figure 5-18b illustrates the effect when the editor suqsystem is made large (30 imple-
mentation components instead of only 3). Now the reduction in component coupling
for the editor subsystem is nearly 46 percent, pushing the overall reduction in CCD to
43.3 percent.

. Cyclic physical dependencies in large, low-level subsystems have the

greatest capacity to increase the overall cost of maintaining a system.

Cyclic coupling at lower levels of the physical hierarchy can have a dramatic effect on
the cost of maintaining clients. As can be seen in Figure 5-18c, when the shape hierar-
chy is made large (30 concrete types instead of only 3), the advantage of the new
design, as measured by CCD, amounts not only to a reduction in coupling of over 90
percent in the shape subsystem but also a reduction of over 44 percent in the editor
subsystem, for a reduction of close to 85 percent overall. When both the shape sub-
system and editor are large, the overall percentage reduction in coupling continues to
improve, as shown in Figure 5-18d.
Section 5.2 Escalation 225

editor subsystem editor subsystem

SIZE = 4 SIZE = 4
CCD = 23 CCD = 19

17.4%

25.1%

SIZE = 4 SIZE = 5
CCD = 16 CCD = 12
NCCD = 2.10 NCCD = 1.14
shape subsystem shape subsystem

combined subsystems combined subsystems

SIZE = 8 SIZE = 9 20.5%
CCD = 39 CCD = 31
NCCD = 1.90 NCCD = 1.28
REDUCTION
ORIGINAL DESIGN NEW DESIGN INCCD

Figure 5-18a: Small Shape Hierarchy (3 Components),

Small Editor (3 Components)
226 Levelization Chapter I

editor subsystem editor subsystem

SIZE = 31 SIZE = 31
CCD = 185 CCD = 100

45.9%

25.1%

SIZE = 4 SIZE = 5
CCD= 16 CCD= 12
NCCD = 2.10 NCCD = 1.14
shape subsystem shape subsystem

combined subsystems combined subsystems

SIZE = 35 SIZE = 36 43.3%
CCD = 201 CCD = 112
NCCD= 1.33 NCCD = 0.90
REDUCTION
ORIGINAL DESIGN NEW DESIGN IN CCD

Figure 5-18b: Small Shape Hierarchy (3 Components),

Large Editor (30 Components)
Section 5.2 Escalation 227

editor subsystem editor subsystem

SIZE = 4 SIZE = 4
CCD = 131 CCD = 73

44.3%

90.3%

SIZE = 31 SIZE = 32
CCD = 961 CCD = 93
NCCD = 8.47 NCCD = 0.69
shape subsystem shape subsystem

combined subsystems combined subsystems

SIZE = 35 SIZE = 36 84.8%
CCD = 1,092 CCD = 166
NCCD = 7.23 NCCD = 1.06
REDUCTION
ORIGINAL DESIGN NEW DESIGN IN CCD

Figure 5-18c: Large Shape Hierarchy (30 Components),

Small Editor (3 Components)
228 Levelization Chapter 5

editor subsystem editor subsystem

SIZE = 31 SIZE = 31
CCD = 1,022 CCD = 154

84.9%

90.3%

SIZE = 31 SIZE = 32
CCD= 961 CCD = 93
NceD = 8.47 NCCD = 0.69
shape subsystem shape subsystem

combined subsystems combined subsystems

SIZE = 62 SIZE = 63 87.5%
CCD = 1,983 CCD = 247
NCCD = 6.30 NCCD = 0.769
REDUCTION
ORIGINAL DESIGN NEW DESIGN IN CCD

Figure 5·18d: Large Shape Hierarchy (30 Components),

Large Editor (30 Components)
Section 5.3 Demotion 229

The important lesson to be learned from this analysis is that a high degree of coupling
associated. with lower-level subsystems can dramatically increase the cost of develop-
ing and maintaining clients and subsystems at higher levels.

To summarize the results of this section: escalating mutual dependencies to a higher

level can be used to convert cyclic dependencies into welcome downward dependen-
cies. The maintenance cost of a subsystem and all of its clients can be reduced signif-
icantly by avoiding unnecessary dependencies among components within the
subsystem itself. At the same time, the subsystem becomes more flexible and there-
fore more reusable. The benefits of the improved design may not be as pronounced for
smaller versions of a system.

5.3 Demotion

Until now we have endeavored to eliminate cyclic dependencies by pushing mutually

dependent functionality higher in the physical hierarchy. In this section we explore the
technique of pushing common functionality down to lower levels of the physical hier-
archy where it can be shared and perhaps even reused. The technique of moving com-
mon functionality to lower levels of the physical hierarchy is referred to in this book
as demotion.

If peer components are cyclicly dependent, it may be possible to

demote the interdependent functionality from each of these
components to a potentially new lower-level (shared) component
upon which each of the original components depends. '

Escalation and demotion are similar in that in either case, cyclic dependencies among
components are eliminated by moving the cyclicly dependent functionality to another
level in the physical hierarchy. Let us start by analyzing what happens during a more
general form of escalation. As illustrated in Figure 5-19, two mutually dependent
components (a) are factored into four components, (b) two of which may be mutually
dependent and two of which are independent. The two higher-level components can
230 Levelization ChapterS,

then be combined (c) if necessary to avoid a cyclic dependency Of, if cohesive, to

reduce physical complexity.

(a) Original (b) Intermediate (c) Final

Cyclic Factored Levelizable
Subsystem Subsystem Subsystem

Figure 5-19: Employing Escalation to Break Cyclic Dependencies

Now contrast this with the general process of demotion. As shown in Figure 5-20, two
mutually dependent components (a) are again factored into four components (b). Two
of the components depend on the two other components, which may be mutually
dependent. The two lower-level components can then be combined (c) if necessary to
avoid a cyclic dependency or, if cohesive, to reduce physical complexity.

(a) Original (b) Intermediate (c) Final

Cyclic Factored Levelizable
Subsystem Subsystem Subsystem

Figure 5-20: Employing Demotion to Break Cyclic Dependencies

Consider the situation shown in Figure 5-21, in which there are two geometric utility
classes, GeomUt i 1 and GeomUt i 12. Each of these utilities provides a suite of functions
that operate on points, lines, and polygons. External clients directly use one, the other,
or both. Unlike geomut; 1, geomut i 1 2 is complex and depends on many other compo-
nents, and even exposes some new types in its interface. Those clients that need only
the basic geometric functionality provided in GeomUt i 1 need not link with the
geomuti 12 component.
Section 5.3 Demotion 231

II geomuti12.h
#ifndef INCLUDED_GEOMUTIL2
#define INCLUDED_GEOMUTIL2

class Line;
class Polygon;

struct GeomUti12 {
static int crossesSelf(const Polygon& polygon);
static int doeslntersect(const Line& linel. const Line& line2);
I I ...
}

#endif

r components

II geomutil.h
#ifndef INCLUDED_GEOMUTIL
#define INCLUDED_GEOMUTIL

class Point;
class Line;
class Polygon;

struct GeomUtil (
static int islnside(const Polygon& polygon. canst Point& pOint);
static int areColinear(const Line& linel, ·canst Line& line2);
static int areParallel(canst Line& linel, const Line& line2);
I I ...
}

flendif
232 Levelization Chapter 5

Initially these two components were levelizable, with geomut i 1 2 depending on

geomut i 1. Unfortunately not all developers are careful about considering the physi-
cal implications of their efforts. One fine day it was discovered that, through care-
less enhancelnent, these two geometric utility components had become mutually
dependent. GeomUti 12: : crossesSel f now depends on GeomUti 1: : areCol i near
and GeomUt i 1 : : i sIns i de now depends on Geomut i 12: : does I ntersect. What
should we do?

We have a couple of alternatives. First we could repackage the functionality so that

there is again a one-way dependency, and this may be the right answer. For example,
we could move doe sIn t e r sec t to Geo mUti 1 and i sIn sid e to Geo muti 1 2. Now there
is no longer a cyclic dependency among these components, although clients of these
components could be affected. (A general technique of repackaging components is
formalized at the end of this section.)

It may also be the case that the two components have taken on distinct characteristics
due to the demands of the clients who depend on them. In that case, it might be more
appropriate to factor out the common functionality and demote it to a lower level in
the physical hierarchy, as shown in Figure 5-22. That is, we can move both the
does I nte r sect and a reCo 1 i nea r functions to GeomUt i 1Co reo

Notice again that these utility classes are merely scopes in which to declare static
member functions-they were never intended to be used to create objects. By
employing the "trick" of making both of the original utilities derive publicly from a
common core, clients of the original utilities will not need to alter their code if one or
more of the utility functions they use is demoted.
Section 5.3 Demotion 233

Figure 5-22: Demoting Common Functionality Among (Utility) Classes

Demotion is a useful tool for reducing the CCD of some designs even when there are
no cyclic dependencies. Suppose a component x depends on only a part of another
complex component y with a high CCD as shown in Figure 5-23a. If we can demote
the common part of y we may be able to spare x some of the physical dependencies
incurred by y (see Figure 5-23b).

other components
other components

(a) Before Demotion (b) After Demotion

234 Levelization Chapters

-
Demoting common code enables independent reuse.

Figure 5-24 illustrates a situation in which the enumerated values defined in sub-
system A are used throughout the entire system, yet subsystem B is otherwise inde-
pendent of subsystem A.

class SubSystemA { class SubSystemB {

I I ... II
public II depends on
enum E {/* ... */}; II SubSystemAts
I I ... II enum E
}; };

Figure 5-24: Poorly Factored System Architecture

.Although there is currently no link-time dependency of subsystem B on subsystem A,

this fact would not be made clear by inspecting an extracted include graph. Instead,
the graph would indicate that the original architect had allowed components in sub-
system B to depend, arbitrarily, on components in subsystem A. In time, normal main-
tenance would inevitably cause more substantial, link-time dependencies of B on A to
take hold, which in tum would affect the link-time cost of maintaining subsystem B.

By creating a separate class (struct) for scoping the enumeration E originally in

SubSystemA and moving that scoped enumeration to a separate component, we c~o
eliminate any physical dependency of subsystem B on subsystem A. As shown 10
Figure 5-25, demoting enumeration E reduces coupling and simplifies the task of
 Demotion 235
section 5.3

understanding the implementation of subsystem B, which, in tum, reduces the cost of

maintaining the entire system.

class SubSystemA { class SubSystemB {

I I .. . II depends on
I I .. . II ScopeOfE's
II... II enum E
}; }:

struct ScopeOfE {
enum E { 1* ... *1 };
};

Figure 5-25: New System Architecture After Demoting the Enumeration

It may seem that placing a single enumeration in its own class is overkill. In some
cases that is so, but not here. Notice that placing this tiny bit of code in its own com-
ponent has freed subsystem B from the considerable maintenance burden of having to
drag around all of subsystem A.

Escalating policy and demoting the inf~astructure can combine to

enhance independent reuse.

Another common example of an architecture that may have an unnecessarily high

CCD can be found in a system that parses a text file to create a runtime data structure
and then operates on that data structure to perform some desired computation.
236 Levelization Chapter 5

In the architecture shown in Figure 5-26, the parser is tightly coupled to the runtime
data structure in a single subsystem at the bottom of the system hierarchy. Conse-
quently, we might expect to see a member function of the form

RuntimeDB::Status RuntimeDB::read(const char *fileName);

where Status is an enumeration nested within class RuntimeDB. Presumably this

read function invokes a parser to load the runtime data structures with information
based on the contents of the file specified by fi 1 eName.

system
I I

..
processor
I I

..
parser &
I runtime-db I
Figure 5-26: Poorly Factored Runtime Database Architecture

At the next level, the processor, which operates off the runtime database, is forced to
depend on the combined parser and runtime database subsystem. The system component
is relatively small and manages both the loading and processing of the runtime database.

Although the above architecture is levelizable, it portends some potentially severe conse-
quences with respect to maintenance and enhancement. The development of a processor
is coupled to both the parser and the runtime database, even though a parser is not needed
for processing. As the system expands and we decide to add more processors, each pro-
cessor must bear the unnecessary burden of linking to the parser during development.

Suppose we decide to change the fonnat of the input file or (worse) make use of mul-
tiple formats. Now, instead of just a single read command, the runtime database must
support several:
section 5.3 Demotion 237

RuntimeDB::Status RuntimeDB::readFormatA(const char *fileName);

RuntimeDB::Status RuntimeDB::readFormatB(const char *fileName);
RuntimeDB::Status RuntimeDB::readFormatC(const char *fileName);

This architecture would require multiple parsers to co-exist in a single subsystem

along with the runtime database, as illustrated in Figure 5-27.

system

processor 1 II processor 2 II processor 3

(-.. /

parser A &
parser B &
parser C &
runtime-db

Figure 5-27: Result of Enhancing a Poor Design

The consequence of this subsystem architecture is that all existing parsers must be
linked in whenever we are:

• enhancing the runtime database,

• enhancing or developing a new parser,
• enhancing or developing a new processor,
• testing any of the above, or
• reusing the runtime database in a standalone product.

In the original architecture, the database depends on the parser to load the informa-
tion. However, on closer examination (see Figure 5-28), we realize that there is (or
should be) an almost acyclic relationship between the runtime database and the parsers.
The database is a low-level repository for information into which clients (such as
parsers) deposit information and from which clients (such as processors) access and
possibly manipulate information. Each parser depends on. the runtime database to
238 Levelization Chapter 5

store the parsed infonnation. The problem lies in the gratuitous "upward" dependency
of the runtime database on a parser.

Gratuitous
Upward
Dependency

... Pn
p1 p2 pn
parser subsystem

r1 r2 rn
runtime database subsystem

Figure 5-28: Close-Up of Poor ParserlDataBase Subsystem Architecture

Escalation and demotion combine to provide an effective solution to this problem. We

can rearchitect the original system (see Figure 5-29) by first escalating the call of the
parser's read function from the RuntimeDB to the system level and then demoting the
common runtime database subsystem. By making the database a "dumb" repository,
complete with a procedural interface for programmatically loading and retrieving
infonnation, each parser becomes "just another client" of the database. Now the sys-
tem manages which files are parsed and then calls the appropriate parser, passing it a
writable (non-const) pointer to the Runt i meDB object that is to be loaded:
section 5.3 Demotion 239

ParserA::parse(RuntimeDB *db, const char *fileName);

If subsequent processing should not alter the runtime database but, say, merely gener-
ate reports, the system can ensure that the database is not overwritten by passing the
processor a read-only (con 5 t) reference to the loaded Run t i meDB:

Pracessorl::quarterlyReport(ostrstream *ostr, canst RuntimeDB& db);

system

··· parser B II parser A I I processor 1 I I processor 2 I ...

runtime-db

Figure 5-29: A More Maintainable System Architecture

With this new architecture, any number of independent processors can be added to the
system and none of them will depend on any parser. Similarly, parsers can be replaced
or added without affecting the runtime database, processors, or other parsers in any
way. With this architecture it is not hard to imagine that the database, parsers, and pro-
cessors could be reused in various combinations in other standalone applications (e.g.,
translators, archivers, and browsers).

As a final example of the power of demotion, consider the subsystem shown in Figure
5-30, in which three related components are cyclicly dependent.
240 Levelization Chapter 5

reporta

Figure 5-30: Cyclicly Dependent Library Subsystem

The Lib r a r y contains a database of low-level infonnation as well as a collection of

heterogeneous Report objects. Almost all kinds of Report supply information that
depends on aggregate statistics, calculated from the low-level data stored in the
Lib r a r y. A statistical utility class, Stat uti 1, is supplied to assist in obtaining this
aggregate infonnation. 6 The common functionality implemented in the (abstract)
Report base class uses StatUtil, which in tum depends on Library, r~sulting in a
cyclic dependency among the 1 i bra ry, S ta tut i 1, and repo rt components.

6 Normally a utility class is either just a struct to provide a scope for a collection of related free
functions or a module (i.e., the class contains only static data members). In either case, it is not
meaningful to instantiate instances of such a class because they contain no state associated with a
particular instance. See "Class Utilities" in booch, Chapter 5, pp. 186-187.
section 5.3 Demotion 241

Factoring a concrete class into two classes containing higher and

lower levels of functionality can fa.cilitate levelization.

The problem arises in part because the single Libra ry class serves as both a reposi-
tory of low-level infonnation and a collection of (higher-level} reports. Fortunately
there are a couple of alternative solutions. First, by demoting the low-level repository
below the rest of the subsystem, we can eliminate the cyclic coupling (as shown in
Figure 5-31).

Figure 5-31: Demoting Low-Level Information in the Library Subsystem

Factoring an abstract base class into two classes-one defining a pure

interface, the other defining its partial implementation--can facili-
tate levelization.
242 Levelization Chapter 5

Another solution begins by recognizing that a single class, Report, has been used for
J two distinct purposes:

1. Providing the interface common to all reports.

2. Providing the implementation that is expected to be common to all reports.

Having a single class serve this dual role is also partially to blame for the cyclic
dependency. The Libra ry depends directly on the interface of the base class, Report,
but only indirectly on its implementation, through the use of virtual functions.

Consider what would happen if we split Report into two classes. The first class would
define the interface specified in the original Report class but would not implement any
of the functions. That is, every function in class Report would now be declared a pure7
virtual function. The second class, call it Report Imp, would derive from Repo rt and pro-
vide the generic report implementation by overriding the appropriate virtual functions.

Now it is possible to break the cyclic dependency in the original system (Figure 5-30)
by demoting only the interface defined in the Repo rt base class below the level of
Library. Class Reportlmp, which implements common functionality and depends on
Stat Uti 1 , remains at a higher level in the physical hierarchy, as shown in Figure 5-32.

Whether we consider these transfonnations to be escalation or demotion is somewhat

arbitrary and unimportant. What is important is that there are two different ways in
which we were able to split a single class into two classes that could then attain dis-
tinct levels in the physical hierarchy.

Which solution is better? This first solution (Figure 5-31) of factoring the Lib r a r y
class is ideal for maintenance, because the low-level repository can be developed
independently of the report collection, as can the statistical utility component. The
second solution (Figure 5-32) forces the entire unfactored Library, and therefore the
low-level repository and statistical utility, to be sandwiched between the interface and
partial implementation of Report. From this perspective, the first solution is prefera-
ble. However, there are other reasons that a single base class should define either the
interface or the factored implementation but not both. Separating the interface from
the (partial) implementation of a base class is discussed in detail in Section 6.4.1

7 The destructor would be declared virtual, but not pure virtual (see Section 9.3.3).
Section 5.3 Demotion 243

Figure 5-32: Demoting "Just" the Interface of the Report Base Class

Factoring a system into smaller components makes it both more

flexible and also more complex, since there are now more physical
pieces to work with.

An even more flexible architecture would result by adopting both transformations.

Since a collection of reports makes sense as an independent abstraction, this architec-
ture can be further improved by allowing the collection of reports to be tested and
reused independently of the Repository.
244 Levelization Chapter 5

Figure 5-33: Adopting All Three Architectural Improvements

In this new architecture (shown in Figure 5-33) the physical structure exhibits more
flexibility than it does in any previous architecture. To avoid unnecessary compile-
time coupling, we would want to separate Report from its partial implementation in
any case. Doing so also allow us to test Report, Co 11 ect i on, and Libra ry by creating
a very simple test-stub, Repo rtC, that does not use or depend on Sta tUt i 1 (see Figure
5-34).
section 5.3 Demotion 245

Factoring the library component is advantageous because it further reduces the physi-
cal coupling in the subsystem. The separation is particularly appropriate because
we've made StatUti 1 depend only on Reposi tory, while Col1 ecti on depends only
on Report, adding considerable flexibility to the hierarchy.

(a) ReportC (b) Colle c t ion (c)Library

subsystem subsystem subsystem

Figure 5-34: Independently Testable and Reusable Subsystems

Demoting Reposi tory enables it to be tested and reused independently (Figure 5-

35a) or in conjunction with StatUti 1 (Figure 5-35b). Individual, complex reports
(such as ReportA) can be tested and reused without having to depend on a collection
that mayor may not eventually hold them (see Figure 5-35c).
246 Levelization Chapter 5

...... :.,:: ......... , .......•........ ::.::,........ .,

~~~:~;::~~~1
(a) Repos i tory (b) StatUt i 1
~~~~~=
·.'-"s,.:i~:.".·.·,:.·.·<.:.· ".,_" .:-,.·.•"_,,,.·."-.·.•,-,i·,• ,,"'~j~
(c) ReportA
subsystem subsystem subsystem

Figure 5-35: More Independently Testable and Reusable Subsystems

Escalation and demotion are closely related. What differentiates escalation from
demotion in character is merely the direction in which a relatively small amount of
offending functionality is moved. In fact, escalation and demotion are actually both
just special cases of the more general repackaging technique illustrated in Figure 5-36.

(a) Original (b) Intermediate (c) Final

Cyclic Factored Levilized
Subsystem Subsystem Subsystem

Figure 5-36: General Repackaging Technique

section 5.4 Opaque Pointers 247

Here, two mutually dependent components (a) are once again factored into four com-
ponents (b). Two of these components, x' and y' , may depend only on each other
while the other two components, x u and y", potentially depend on each of the other
three components. The two respective pairs of, perhaps, mutually dependent compo-
nents may now be recombined into two new components (c). Component u now
depends on component v, which is independent. This general repackaging technique
was applied informally to the components geomut i 1 and geomut i 1 2 discussed at the
beginning of this section.

To summarize: we can sometimes eliminate mutual dependencies among components

by factoring commonly needed functionality and moving it lower in the physical hier-
archy. Demotion is useful not only for improving cyclicly interdependent designs, but
also for reducing the CCD in acyclic architectures as well. Demoting common sub-
systems improves both maintainability and extensibility. A properly factored system
is more flexible in th~t its internal physical dependencies allow its components to be
independently tested and reused in a wider variety of useful ways.

5.4 Opaque Pointers

Normally we assume that if a function uses an object of type T, it does so in a way that
requires knowing the definition of T. That is, in order to compile the body of the func-
tion, the compiler needs to know the size and layout of the object it uses. The way a
compiler learns the size and layout of an object in C++ is for the component using the
object to include the header file of the component containing the object's class definition.

DEFINITION: A function f uses a type T in size if compiling the

body of f requires having first seen the definition of T.

If a function body can be compiled having seen only the declaration of type T (e.g.,
c 1 ass T ;), then that function itself does not depend on the definition of T. The signifi-
cance of using a type in size is that such use induces an immediate compile-time
dependency on the component defining T. (Avoiding unnecessary compile-time
dependencies is the topic of C_hapter 6.) The body of a function f using type T in name
but not in size typically, however, calls one or more functions in other components
that, in tum, do depend on the definition of T. In this situation there would continue to
be a link-time dependency of f on T.
248 Levelization ChapterS

DEFINITION: A function f uses a type T in name only if compiling f

and any of the components on which f may depend does not require
having first seen the definition of T.

If a function f and all components on which f depends can be compiled and linked,
having seen only the declaration but not the definition of T, then f is said to use T in
name only. For example,

II util.h
#ifndef INCLUDED_UTIL
#define INCLUDED_UTIL

class SomeType; II used In name only

struct Uti 1 {
SomeType *f(SomeType *obj);
}
II util.c
#endif #include "util.h ll

SomeType *Uti 1: : f( SomeType *obj)

{
static SomeType *lastType=O;
return obj ? lastType = obj : lastType;
}

illustrates a function f using a type SomeType in name only. The significance of using
a type in name only is that there is no implied physical dependency by such use-
even at link time. Without the physical dependency, the coupling is all but eliminated.

Similar definitions can be constructed for a class that uses a type in size or in name
only. Even more useful is that these definitions can be extended to apply to compo-
nents as a whole.

DEFINITION: A component c uses a type T in size if compiling c

requires having first seen the definition of T.
section 5.4 Opaque Pointers 249

DEFINITION: A component c uses a type T in name only if compiling

c and any of the components on which c may depend does not require
having first seen the definition of T.

We use the first of these two definitions in Chapter 6. For now, we focus on the rami-
fication of the second of these two component-level definitions. Note that, as illus-
trated in Figure 5-37, a component u that uses a T object in name but also depends on
another component v that, in tum, uses T in size, by transitivity, does not use T in name
only. Component.u depends physically on component v and indirectly on component t.

Depends On

Uses (In N~me)

Uses (In Size)

t
Figure 5-37: Component u Does Not Use Type T In Name Only

The dashed-line form of the uses notation "0- - - - " denotes that the use is "in name
only" and imposes a conceptual but no physical dependency.
250 Levelization ChapterS

Here we deviate from the notation for "by-reference" dependencies suggested by

Booch8 for two reasons: (1) the logical meaning of this new In-Name-Only symbol is
identical to its In-Size counterpart-it is only the physical implications that differ; and
(2) use in name only (unlike use by reference) expressly denies any direct or indirect
compile- or .link-time dependency. For our purposes, three flavors of uses notation
suffice:

Our Notation Booch Notation

Uses In The Interface Uses In The Interface
0 0

0- _ yses !n_1!te Interfa_c~ __

(In Name Only)
HasNHoldsA
• Uses In The Implementation
• ( Unspecified)
HoldsA
(By Reference)
RasA
• (By Value)
0

Components that use objects in name only can be thoroughly tested,

independently of the named object.

Situations involving using a type in name only rarely arise naturally; they are usually
contrived to avoid unwanted physical dependencies. Using a type in name only is pos-
sible when the component doing the "using" refers to the object only by pointer or ref-
erence, and never interacts with the object directly in any way other than to hold its
address.

8 booch, Section 5.2, Figure 14, p. 191.

Section 5.4 Opaque Pointers 251

II handle.h
#ifndef INCLUDED_HANDLE
#define INCLUDED_HANDLE

class Faa;

class Handle {
Fao *d_opaque_p;

public:
HandleCFoo *foo) d_opaque_pCfoo) {}
void set(Foo *foo) { d_opaque_p = foa; }
Foo *get() canst { return d_opaque_p; }
};

#endif

Figure 5-38: Handle Class that Uses Faa in Name Only

A pointer is said to be opaque if the definition of the type to which it points is not
included in the current translation unit. Figure 5-38 shows a trivial example of a class
that holds an opaque pointer to an instance of some class named Faa. The client of the
Han d 1e class will ultimately have to include the header file of a component that
defines Faa in order to come up with a Faa object. For testing purposes, any class Foa
will do, including even a mere class declaration as Figure 5-39 demonstrates.

II handle.t.e
#include "handle.hl!
#include <assert.h>

rna inC)
{
Faa *pl = CFaa *) OxBAD;
Foa *p2 = CFoa *) OxBOB;
Handle handleCpl);
assertCpl == handle.get());
h.setCp2);.
assertCp2 == handle.getC));
}

Figure 5-39: Trivial Test Driver for handl e Component

The significance of this example is that it was possible to exercise the functionality of
the Han d 1e class completely without having to include or link to any component
defining class Faa. Such is a litmus test for whether another type has been used not
only opaquely, but also in name only.
252 Levelization ChapterS

,
«<ii

~.:. . . . . . . ."••. •. .i•·. . .f!.·•,.·•·.·.l.•.•·. ". •. .•·. . . .

.»,

c,.·. ·.;.·• p
............> . I
. . ·.• .·• e. •.'•. ·."' ....•...
I.••.·.• . ·.·.I
.•. . .
_ . i ... )

If a contained object holds a pointer to its container and implements

functionality that depends substantively on that container, then we
can eliminate mutual dependency by (1) making the pointer in the
contained class opaque, (2) providing access to the container pointer
in the public interface of the contained class, and (3) escalating the
affected methods of the contained class to static members of the
container class.

When developing a particular application, it is common for a higher-level object to

store information in objects defined at the lower levels of the physical hierarchy. If
that information is in the form of a user-defined type, there is the potential for causing
the subordinate object to depend on that type. As long as the subordinate does not
need to make any substantive use of the type on its own, there is no need for the sub-
ordinate to include the definition of the type.

Suppose Sc r e e n is a container for Wid get objects, and suppose furthermore that
each Widget holds a pointer, d_parent_p, identifying the Screen to which the
Widget belongs. Now consider the interfaces for the widget and screen compo-
nents suggested in Figure 5-40, and in particular the accessor member function
numberOfWidgetslnParentScreen of class Widget.

This function allows a client holding nothing but a Wi dget to find out how many other
Wi dget objects there are in the Screen to Whi ch the Wi dget belongs. From a pure
usability perspective, this architecture may seem appealing; from a maintainability
perspective, it is expensive.
section 5.4 Opaque Pointers 253

II screen.h II widget.h
#ifndef INCLUDED_SCREEN #ifndef INCLUDED_WIDGET
#define INCLUDED_SCREEN #define INCLUDED_WIDGET

class Widget; class Screen;

class Screen { class Widget {

Widget *d_widgets_p; Screen *d_parent_p; II Screen to which
I I ... II ... II this widget belongs
public: public: -
Screen(); Widget(Screen *screen);
I I ... II
void addWidget(const Widget& w);
/ I ... II operations involving parent screen
int numWidgets() canst;
I / ... int numberOfWidgetsInParentScreen() canst;
};
I/ ...
#endif };

#endif

(a) Container Component screen (b) Contained Component wi dget

Figure 5-40: ScreenIWidget Design Causing Cyclic Dependency

The problem with the maintainability of this design is that in order to implement the
numberOfWi dgets InPa rentScreen method in the wi dget. c file, we will need to
"ask" the parent Sere en for this information. Asking Sere e n anything implies having
seen its definition, which is accomplished by first including s ere en. h in wid get. c.
But doing so leads to the unlevelizable situation depicted in Figure 5-41.
254 Levelization Chapter 5

screen widget

II widget.c
#include "widget.h"
#include "screen.h"
I I ...
int Widget::numberOfWidgetslnParentScreen() canst
{
return d_parent_p-)numWidgets();
}
II

screen.h widget.h

screen widget

Figure 5-41: Class Wi dget "Knows About" Container Class Screen

The fundamental problem here is that a Wid get is trying to do more than it should. A
Wid get has functionality that makes sense in its own context, but it cannot in general
know about other,Widget objects without asking its parent Screen. Consider again
the analogy to a corporation. You can ask any employee, "What are you doing?" and
the employee should be able to tell you. Similarly, you can always ask the employee,
"Who is your boss?" In contrast, try asking the employee for the number of employ ..
ees who work for his or her boss. In general the employee will not know the answer,
and will need to go to the boss and ask.

Actually it is none of the employee's business how many other employees work for
the boss. Consider this alternate approach. Suppose you want to know how many
employees work for ,my boss. Instead of asking me that question, ask me, "Who is
section 5.4 Opaque Pointers 255

your boss?" I will tell you, and then you can go and ask her yourself how many
employees work for her. If she wants to tell you, she will.

The use of opaque pointers (used in name only) can serve to break unwanted cyclic
component dependencies. Turning back to our programming example, consider the
alternate definition for the wi dget component shown in Figure 5-42. In this usage
model, it is possible to ask the Wi dget for its parent Screen. We will then be able to
ask the parent Screen about its other Wi dget objects (or anything else, for that mat-
ter). The principal benefit for this model, however, is that component wi dget no
longer depends on component screen at either compile or link time. The dependency
of wi dget on screen is now in name only_

II widget.h
#ifndef INCLUDED_WIDGET
#define INCLUDED_WIDGET

class Screen;

class Widget {
Screen *d_parent_p; II screen to which this widget belongs
I I ...
public:
WidgetCScreen *screen);
I I ...

II operations involving parent screen

Screen *parentScreen() const;

};
II widget.c
#endif #include "widget.hl!
#include "screen.h" II no longer needed

I I ...

Screen *Widget::parentScreen() canst

{

Figure 5-42: Modified Architecture for wi dget Component

The new component dependency graph for screen and wi dget is shown in Figure 5-
43. With this new architecture, it is possible to test all the functionality .of wi dget
256 Levelization Chapter 5

independently of the screen component. Other components that use widgets but do
not care about screens need not include screen. h or link to screen. o.

Level 2:
uses in the interface
(In Name Only)

Levell:

widget

Figure 5..43: Levelizable Component Dependency for wid get and s c r e e n

A small test driver that demonstrates the physical independence of wi dget on screen
is shown in Figure 5-44.

II widget.t.c
#include Itwidget.hlt
#include <iostrearn.h>

class Screen; II not necessary when including widget.h

rna i n ( )
{
Screen *const screen = (Screen *) Oxbad;

const Widget widget(screen);

if (screen != widget.parentScreen(» {
cout « IIError!" « endl;
}

1/
}

Figure 5..44: Test Driver for wi dget Component in Isolation

An immediate consequence of this architectural change is that clients must perform

two operations instead of one to retrieve the number of Wi dget objects in the parent
Screen:
section 5.5 Dumb Data 257

widget.parentScreen()-)numWidgets()

For convenience, these two operations could be combined into a s tat i c member
function of Sere en or some other, higher-level class. Instead of saying

widget.numberOfWidgetslnParentScreen()

you would say

Screen::numberOfWidgetslnParentScreen(widget)

to obtain the value. In either case, this interface forces clients to look outside the
wi dget component's interface in order to obtain the answer to their question.

Note that when moving functionality from the contained object to the container, the
first argument of each new static member will be either a can s t reference or a nOD-
canst _pointer to the contained object-depending, respectively, on whether the
original member was a canst or non-canst function. The rationale for this style of
argument passing is taken up in Section 9.1.11.

To recap: we were able to achieve an acyclic component dependency graph by making

class Wid get's internal Sc r e en pointer opaque and by moving the part of Wid get that
made substantive use of class Screen out of Wi dget and into the Screen class itself.
We also exposed the Sere en type in the public interface of Wid get and made it neces-
sary for clients of wi dget to look outside that component for the answers to certain
kinds of questions. But in so doing, mutual physical dependency was replaced with
conceptual cooperation: the lower-level object agrees only to hold on to information
(specified in name only) for use at higher levels.

5.5 Dumb Data

The term dumb data refers to a generalization of the concept of opaque pointers. Dumb
data is any kind of information that an object holds but does not know how to interpret.
Such data must be used in the context of another object, usually at a higher level.

Let's consider what might be involved in implementing a simplified subsystem to model

a racetrack for horses. As a starting point, we would like to be able to ask questions such
as those illustrated in Figure 5-45. The top-level component should provide the capability
to iterate over the races and to identify a horse by name. To make this example interest-
ing, it should also be possible for a track to accept bets and to redeem wagers.
258 Levelization Chapter 5

void questions(const Track& track,

canst Race& race,
const Horse& horse)
{
II 1. What races do you run here?
for (RaceIter itl(track); itl; ++itl) {
cout « itl().number() « endl;
}

II 2. What time does a given race start?

cout « race.postTime() « endl;
II 3. What horses are running in a given race?
for (Horselter it3(race); it3; ++it3) {
cout « i t3(). name() « endl;
}

II 4. What is the number of this horse?

tout « horse.number() « endl;
}

Figure 5-45: Some Common Questions Asked at a Horse-Racing Track

An initial cut at the top-level track component is given in Figure 5-46. In this architec-
ture, a T rae k holds a collection of Rae e objects and supplies a Ra eel t e r to iterate
over today's races at the track. The Track takes bets and issues (pointers to) Wager
objects, which can be redeemed after the race is completed.

II track.h
#ifndef INCLUDED_TRACK
#define INCLUDED_TRACK

class Horse;
class Race;
class RaceIter;
class Track;

class Wager {
const Horse& d_horse;
double d_amount;
I I ...
Wager(const Horse& horse, double amount); II For track's use only
Wager(const Wager&); II i.e., not for use
Wager& operator=(const Wager&); II by the public ..
friend Track;
Section 5.5 Dumb Data 259

public:
const char *horseNameC) canst;
int raceNumber() canst;
Track& track() canst;
double amount() canst;
};

class Track {
Race *d_races_p;
I I ...
friend Racelter;

public:
I I ...
canst Race *loakupRace(int raceNumber) canst;
canst Horse *loakupHorse(canst char *horseName) const;
Wager *betCconst Horse& horse, dauble wagerAmount);
dauble redeem(Wager *bet) canst;
};

class RaceIter {
I I ...
public:
Racelter(const Track& track);
void operator++();
operator canst vaid *() canst;
canst Race& operator()() const;
};

#endif

Figure 5-46: Header for Top-Level Component t r a c k

Each Ra ce object maintains the number of that race, the post time for that race, and
the collection of horses running in that race. The race component also provides a
HorseI ter to iterate over the horses running in a specified Race. Given a Race object,
it is possible to determine at which track the race will be run. A rough version of the
race component is shown in Figure 5-47.

II race.h
#ifndef INCLUDED_RACE
#define INCLUDED_RACE

class Horselter;

class Race {
I I ...
friend Horselter;
260 Levelization ChapterS

public:
Race(const Track& track, int raceNumber~ double postTime);
// ...
int number() const;
double po~tTime() const:
canst Track *track() const:
};

class Horselter {
// ...
public:
HarseIter(const Race& race);
vaid operator++();
operator canst void *() canst;
canst Horse& operator()() const;
};

#endif

Figure 5-47: Header for the Intermediate-Level Component race

A Horse is defined at the lowest level of the racetrack subsystem's physical hierarchy.
A Horse maintains its name and number, and it can be used to determine in which
race it is scheduled to run. A first cut at our leaf-level horse component is sketched in
Figure 5-48.

#ifndef INCLUDED_HORSE
#define INCLUDED_HORSE

class Race;

class Horse {
canst Race& d_race:
char *d_name_p;
int *d_number;
// ...
public:
Horse(const Race& race, canst char *HorseName, int harseNumber);
// ...
canst char *name() canst;
int number() canst;
const Race *race() const;
};

1foendif

·Figure 5-48: Header for the Leaf-Level Component horse

section 5.5 Dumb Data 261

In this initial implementation, a Wag e r is implemented with only two data members as
follows:

class Wager {
canst Horse& d_horse:
double d_amount;
// ...
public:
// ...
};

Holding a pointer to a H0 r s e, it is possible for clients at sufficiently high levels to use

the uniquely identified Horse to obtain a pointer to the Race, anywhere in the world,
in which that H0 r s e will run. The Ra ce pointer can then be traversed, and the resulting
race object used to obtain a pointer to the track where that race will be held.

The functionality for the horse racetrack system described above implies maintaining
a cyclic internal data structure: Each T rae k knows the races that it holds, each H0 r s e
knows in which race it runs, and each Ra ce knows both the track in which it is held
and the horses that will participate in it. However, this data structure can be imple-
mented with acyclic physical dependencies by using opaque pointers as shown by the
component/class diagram of Figure 5-49.

horse

Figure 5-49: Component/Class Diagram for Racetrack Subsystem

262 Levelization Chapter 5

The original architecture presented for the racetrack subsystem has no cyclic physical
dependencies but is nonetheless cyclicly dependent in name. Although having two com-
ponents that each know the names of one or more objects defined in the other compo-
nent is not necessarily bad, there are trade-offs to be made that will be discussed shortly.

Suppose that, instead of identifying the objects in this system by their absolute
addresses, we identify them in terms of indices into a sequence of objects that has
meaning only in the context of the parent object.

The Track would then hold a sequence (array) of Race objects, and each Race would
have an associated integer "index." The Ra ce index would be meaningful only in the
context of a T r ac k object. Since the Ra c e indices can be made to correspond to the
publicly accessible Ra c e numbers, the need for a Ra c e I t e r is reduced, provided we
supply an accessor for Tr a c k to report the total number of races held today.

By the same argument, each Horse in a Race is naturally assigned a number. Given a
Race that has a sequence of horses, we can identify the Horse within a Race by sup-
plying its index relative to that race. We therefore can also dispense with the
H0 r s e I t e r for Race.

When it comes to redeeming wagers, the Trae k defines a context that is much smaller
than the entire address space (accessible via pointers). In the original implementation,
we used opaque back pointers beginning with H0 r s e, and moved in a bottom-up fashion
to arrive at the Race and finally the Track. In the proposed implementation, the limited
context of the Tra c k is exploited to identify the Ra ce and Ho rs e using a pair of integer
indices as shown in Figure 5-50.

class Wager {
canst Track& d_track:
double d_amount;
short int d_racelndex:
short int d_horselndex;
// ...
public:
Wager(const Track& track,
int horseNumber,
int raceNumber,
double amount);
canst Track& track() canst;
double amount() canst;
int horseNumber() canst;
int raceNumber() canst;
// ...
};
section 5.5 Dumb Data 263

class Track {
Race *d_races_p;
int d_numRaces;
// ...
public:
Wager *bet(int race, int horse, double amount):
double redeem(Wager *bet) const;
canst Race *lookupRace(int raceNumber) const;
constHarse *lookupHorse(const char *horseName) const;
canst .Horse *lookupHorse(const Race& race, int horseNumber) const;
int numRaces() canst;
// ...
};

Figure 5-50: Modifications to Component track

Observe that, because of the very limited, context, we can safely use 16-bitinstead of
32-bit integers. This fact could be significant if the' number of outstanding\vagers at
anyone time becomes very large. For example, on my 32-bit machine, where a double
is 8 bytes long and naturally aligned,9 the size of the wager objects drops from 24 to
16 bytes when we make the indices s h0 r t integers-a savings of 33 percent!

Figure 5-51 illustrates the revised architecture for the racetrack subsystem. The new
system is significantly simpler. This system has no cyclic dependencies between com-
ponents-not even in name-and significantly fewer classes. The principal change
was simply the way in which a H0 r s e is identified.

Dumb data can be more convenient and occasionally more compact than opaque
pointers for identifying other objects. Had the new Wag e r object identified the Ra c e
and H0 r s e by opaque pointer instead of s h0 r t integer index, the size of Wag e r would
again be 24 instead of 16 bytes on my machine.

Another advantage is that the values stored as dumb data are not machine addresses and
therefore contain meaningful values that can be tested explicitly. In the horse-racing
application, the indexed approach is particularly appealing, because the indices
(which are publicly accessible) do have legitimate utility in the user domain. It is not
uncommon to hear a frequent patron of the track request of a parimutuel ticket agent
at the betting window: "Gimme 2 bucks on number 4 in the 9th (to win)!"

9 Natural alignment is discussed in Section 10.1.1.

264 Levelization Chapter 5

In Name Only

Figure 5-51: Revised Component/Class Diagram for Racetrack Subsystem

A disadvantage of the indexed approach is that it does sacrifice a fair degree of type
safety compared to opaque pointers in that the Race and Horse indices are just inte-
gers. Another drawback is that this implementation forces the Race and H0 r s e collec-
tions to be indexed rather than to remain arbitrary collections. The resulting erosion of
encapsulation could easily have a negative impact on maintainability if exposed to the
general pUblic.

In situations other than our horse-racing example, the dumb-data indices used to iden-
tify subobjects in this way might very well be meaningless to clients of the subsystem.
For these reasons, the use of dumb data is typically an optimized implementation tech-
nique encapsulated within a subsystem and not exposed at the higher levels of a system.

Dumb data can be used to break in-narne-only dependencies,

facilitate testability, and reduce implementation size. However,
opaque pointers can preserve both type safety and encapsulation;
dumb data, in general, cannot.
section 5.5 Dumb Data 265

As a similar but more serious example, consider the task of modeling the connectivity
within a circuit consisting of a heterogeneous collection of electrical components. 10 A
gate-level circuit, such as the one used to introduce levelization in Figure 4-10 of Sec-
tion 4.7, can be represented as a graph consisting of nodes (called gates) and edges
(called wires). Each gate has a collection of electrically distinct connection points
(called terminals). Conceptually, representing a circuit amounts to maintaining a hetero-
geneous collection of gates and a homogeneous collection of bidirectional wires. Each
wire is attached to two distinct terminals within the circuit, establishing connectivity.

In a traditional implementation, a circuit might contain a collection of terminals,

defining the primary inputs and outputs for the circuit. Each gate in the circuit would
also contain a collection of terminals. Wires are not explicit objects in this model.
Instead, each terminal contains a collection of pointers to (other) terminals. Pointing
to another terminal implicitly establishes a connection to that terminal. In the example
shown in Figure 5-52, the terminal z of gate gO is connected to the terminal x of gate
9 1; therefore, terminal z of gO would hold a pointer to terminal x of 9 1. By symmetry,
terminal x of 9 1 is also connected to terminal z of gO, so x of 9 1 would also hold a
pointer to z of gO.

a x e
gO z -
b Y '--
x
91 z d
c y
C

Figure 5-52: Circuit C Implemented in Terms of1\vo Gates, gO and gl

In order to traverse the graph, a Te rmi na 1 must maintain an opaque pointer to its par-
ent Ga te or Ci rcu it. Note that eire ui t can be treated as just a special kind of Ga te

10 Thisexample describes the application of dumb data in a very different context. The basic tech-
nique, however, is the same as for the racetrack example.
266 Levelization ChapterS

that contains instances of other gates. I1 Cyclic physical component dependencies can
be avoided by using opaque pointers as shown in the partial component/class diagram
of Figure 5-53 (with collection iterators omitted).

Here again there is an opportunity to break even the nominal cyclic dependencies by
defining a connection "in context." If a Circuit contains,an indexed collection (an
array) of gates, and similarly each Gate contains an array of tenninals, then we can
identify a connection point in the context of a Cire ui t as a simple pair of integer indices.

Figure 5..53: Partial Component/Class Diagram for Ci rcu; t Implementation

11 This example illustrates another instance of recursive composition-a design pattern called
Composite in gamma, Chapter 4, pp. 163-173. This pattern was seen previously in terms of Node,
Fi 1 e, and Di rectory in Figure 4-13 of Section 4.7. The Composite design pattern has been used
effectively to implement hierarchical circuit descriptions.
section 5.5 Dumb Data 267

Consider again the example of Figure 5-52. Suppose the implementation of the circuit
consists of an array of two gates, gO and 9 1, with indices 0 and 1, respectively. The
tenninals for both gO and gl are x, y, and z, and happen to have indices 0, 1, and 2
respectively. We can now describe the connection point "terminal x of gate 9 1" as the
pair of integer indices (1, 0). We can similarly describe the connection point z of gO as
the coordinate pair (0, 2).

By convention, we can identify the enclosing circuit by using an index outside the legal
range for gates indices" (such as -1). If the circuit's terminal a has index 0, its connec-
tion coordinates could be represented as the pair of indices (-1; 0). The complete list of
connections for this circuit, described in terms of integer coordinates, is provided in
Figure 5-54.

C.a - ( - 1 , 0) ...
...
..• ( 0, 0) - gO.x
C.b
C.c
gO.z
= ( - 1 , 1)
-
-
( - 1 , 2 ) ...
( o, 2) ...
..• (
(
o, 1 ) = gO.y
1 , 1 ) = gl.y
( 1 , 0) = gl.x
gO.z - ( o, 2) ... • ( - 1 , 4) - C.e
1 , 2 ) ...
gl.z = (
• ( - 1 , -3) - C.d

Figure 5..54: Representing Connectivity Using Integer Indices

A pair of integers has no physical dependency on anything. We can therefore define a

Connect i on class in a leaf component as follows:

class Connection {
int d_gatelndex;
int d_terminallndex;

public:
Connectian(int gatelndex, int instancelndex);
int gatelndex() canst;
int terminal Index() canst;
};

Figure 5-55 illustrates a completely levelizable component hierarchy in which

Connection, ConnectionCollection, Terminal, TerminalArray, Gate, GateArray, -'

and finally Ci r cui t can be tested and verified in order.

The graph-like nature of Ci rcui t is not evident from the subcomponents. The con-
nectivity of the circuit is not established until the level of the component that defines
the Gat eAr ray class, because it is only at that level that sufficient context exists to
268 Levelization ChapterS

understand the implied graph. Users of Cire u i t need not necessarily be exposed to
the lower-level Ga te and Te rmi n a1 classes, and may wind up "programming" the cir-
cuit by specifying gates and terminals by names that are translated to indices internally.

Figure 5-55: New Component/Class Diagram for Ci rcui t Implementation

To conclude this section: dumb data is a generalization of opaque pointers that can
facilitate the implementation of subsystems, in which low-level objects must implic-
itly refer to other low-level objects. This technique is especially indicated where these
references ne~d not be interpreted at the lower levels of the subsystem, but only in the
context of some (usually) higher-level object. This restricted context can allow for
section 5.6 Redundancy 269

more compact implementations, though it is at the expense of both type safety and
encapsulation. The use of dumb data is typically a low-level implementation detail
and often not exposed in the interfaces of higher-level subsystems.

5.6 Redundancy

Reuse of any kind implies some form of coupling. In some cases the coupling may be
severe. In this book, redundancy refers to the technique of deliberately repeating code
or data in order to avoid unwanted physical dependencies brought on by reuse.

The additional coupli~g associated with some forms of reuse may

outweigh the advantage gained from that reuse.

Redundancy is indicated when the functionality exists in a separate physical unit, the
amount of functionality to be reused is relatively small, and the amount of coupling
that would result is so disproportionately large as to outweigh the benefit of the reuse.
For cases where the amount of reuse would be substantial, it is often appropriate to
demote the common code to a lower level where it can be shared.

Even within a single subsystem there is a threshold below which reuse of external
functionality may not be advantageous. Consider two large components that are inde-
pendent. It is possible that one of these components implements a tiny piece of func-
tionality (such as mi n, max, etc.) that the other could reuse. Demoting this tiny piece of
the implementation to a separate component would unjustifiably increase the physical
complexity of the subsystem. Causing one of these components to depend on the
other just for such a small amount of reuse would unjustifiably increase the CCD of
the subsystem. Allowing one component to dominate the other reduces flexibility for
adding other dependencies resulting from future enhancements. Sometimes a viable
alternative to reuse is simply to repeat the code and avoid the coupling.

As a common, practical example, consider the situation illustrated in Figure 5-56, in

which some low-level object, Ce 11, has a name. The name is specified when the
object is constructed, cannot be changed throughout the lifetime of the object, and is
270 Levelization Chapter 5

destroyed when the object is destroyed. An accessor in the public interface of the
object supplies the name (as a const char *) on request. Other than the name, there
is no use made of St r i n 9 in this object.

str cell

II cell.h II cell.h
#ifndef INCLUDED_CELL #ifndef INCLUDED_CELL
#define INCLUDED_CELL #define INCLUDED_CELL

#ifndef INCLUDED_STR
#include "str.h"
#endif

class Cell { class Cell {

String d_name; canst char *d_name_p;
I I ... j I ...
public: public:
Cell(const char *name); Cell (canst char *name);
----Cell ( ) ; ""Cell ();
I I ... I I ...
canst char *name() canst; canst char *nameC) canst;
II II
}; };

1tendif #endif

(a) Using the Stri ng Class (b) Reimplementing St r i n 9 's Functionality

Figure 5-56: Two Ways to Implement an Object that Has a Name

The use of St r i n 9 here is an encapsulated implementation detail of the Ce 11 class.

The advantage of using St r i n 9 is that there is no need to use the new operator
(directly) in the implementation of the Ce 11 's constructor, to worry about allocating
the extra byte for the trailing null, or to copy the incoming St r i n 9 to the newly
section 5.6 Redundancy 271

allocated buffer. Perhaps the biggest benefit is not having to worry about deleting this
St ring in the Ce 11 's destructor.

To experienced C programmers, none of the above should present any noticeable main-
tenance problem. The disadvantage of depending on St r i n9 is that it is extra baggage
that must follow the ce 11 component around. If s t r is not part of the same subsystem
or depends on other components, then using St r i n9 (instead of just a c h a r *) could
result in having to drag around other components or even libraries, further increasing the
burden of using Cell.

As defined in Figure 5-56a, Cell has a Stri ng and therefore depends on component
5 t r in size. All clients of Ce 11 will be saddled with not just a link-time but also a
compile-time dependency on component str. This problem is avoided if Cell is
defined as shown in Figure 5-56b. (The issues surrounding unnecessary compile-time
dependencies are the subject of Chapter 6.)

In cases such as the one shown in Figure 5-56, avoiding coupling to the 5 t r component
probably outweighs the advantages of reuse. Such would not be the case if the ce 11
component makes any significant use of St ri ng's capabilities (e.g., concatenation) or
if St r i n9 appeared many times in the definition of Cell.

Supplying a small amount of redundant data can enable the use of an

object in name only, thus eliminating the cost of linking to the defini-
tion of that object's type.

Redundancy can be used effectively in a variety of ways and in conjunction with other
techniques to reduce physical dependencies. In particular, choosing to use objects in
name only can be effective not only for breaking cyclic dependencies within a sub-
system but also for reducing the physical dependency upon other subsystems. Some-
times, however, it is necessary to supply a small amount of redundant information in
order to keep certain objects opaque.

Consider the scenario illustrated in Figure 5-57. We are trying to implement a shape
analyzer on top of a large shape subsystem consisting of, say, 1,000 components.
272 Levelization Chapter 5

CCDAnalyzerSubsystem = 1,001 + 3 • 1,002 + 1,005 = 5,012

Component Level Number

Dependency
analyzer subsystem

Component Level Number

Dependency

shape subsystem

Figure 5-57: ShapeAna 1yzer Forced To Use Highly Coupled Shape Subsystem
section 5.6 Redundancy 273

Fortunately we need to make use of only a small portion of this subsystem, in particu-
lar, the shape component. Unfortunately this component is fully dependent on the rest
of its subsystem, giving shape a disproportionately large link cost (1,000 units as
measured by its component dependency). The CeD for just the five components of
the analyzer subsystem (that is, excluding the local link cost of maintaining the shape
subsystem) is 5,012.

Often there are sophisticated container objects (such as a priority queue) that hold
other objects, but that need not depend on the contained object in any substantive way.
The job of the ShapeQueue is to maintain a heap of Shape objects ordered by area.
The Shape class supplies a public member function to return its area. Designing
Sha peQueue to use Sha pe's a rea ( ) member directly would tie the cost of developing
and maintaining the ShapeQueue (and all of its clients) to the unusually large CCD
imposed by Shape.
)

Figure 5-58 depicts an alternative architecture, motivated entirely by reducing the cost
of maintenance and testing. Instead of having ShapeQueue get the area data directly
from a Sh a pe, aSh a peMa n a ge r extracts this value and enters it, redundantly, along with
each opaque Shape pointer into the ShapeOueue. The rest of ShapeAnalyzer's imple-
mentation has been refactored so that all substantive use of class S ha pe now occurs
only in the shapemanager component, with some additional redundant data (i.e., area)
being stored in each ShapeOueue entry for use by components x, y, and z).
274 Levelization Chapter 5

CCDanalyzersubsystem = 1 + 1,001 + 3· 2 + 1,006 = 2,014

Level
Number
Component
Dependency

analyzer subsystem

Component
Dependency
Level Number

shape subsystem

Figure 5-58: Reducing CCD by Using Redundant Data and Opaque Pointers
Section 5.7 Callbacks 275

Packaging subsystems so as to minimize the cost of linking to other

subsystems is a design goal.

The reduction in maintenance cost associated with the analyzer subsystem of nearly
60 percent is not unusual, nor is the relatively large cost associated with linking to a
large, highly interdependent subsystem. A well-designed subsystem will usually con-
tain a substantial proportion of components that do not depend on any other sub-
systems, and few components that depend on huge, tightly coupled subsystems such
as the one containing Shape.

In short, reuse is rarely without cost, and its benefit must be weighed against the cost
resulting from increased coupling. Very often that cost comes in the form of increased
physical dependence. Techniques used to reduce physical coupling, such as opaque
pointers, occasionally require providing a small amount of redundant information in
order to be applied successfully. In such cases the amount of savings in terms of cou-
pling will dictate the amount of redundancy that is tolerable.

5.7 Callbacks

A callback is a function, provided by a client to a subsystem, that allows that sub-

system '~o perform a specific operation in the context of the client.

As a.simple example, consider the C Library function qsort, 12 which is an imple-

mentation of the Quicksort algorithm:

#include <stdlib.h>

void qsort(const void *base,

size_t numElements,
size_t sizeofElement,
int (*compare)(const void *eleml. canst void *elem2);

12 plauger, Chapter 13, pp. 357-358.

276 Levelization Chapter 5

The first parameter of qsort, base, indicates the starting location of a homogeneous
array of objects whose type is unknown to the qsort routine. The second parameter,
numEl ements, indicates the number of objects in the base array. The third parameter,
s i zeofEl ement, indicates the uniform size of each element (as defined by the s i zeaf
operator). The fourth and final parameter, compa re, is a pointer to a callback function.

The qsort function assumes that this callback function, compa re, will correctly deter-
mine whether the first of the objects, e 1eml, implied by its two generic pointer argu-
ments should be considered less than, equal to, or greater than the second argument,
e1em2, by returning a negative, 0, or positive value, respectively.

To illustrate a benign use of callbacks, consider the simple problem of sorting a collec-
tion of Cartesian points based on their relative distances from the origin of a two-dimen-
sional coordinate system. Figure 5-59a depicts an instance of this problem containing
six points labeled a through! The definition of a Poi nt is given in Figure 5-59b.

II point.h
#ifndef INCLUDED_POINT
#define INCLUDED_POINT

class Point {
int d x;
15 G) i nt d_y; C

12 public:
Point(int x. int y) : d_x(x). d-y(y) {}
Point(const Point& p) :
9 d_x(p.d_x), d-y(p.d-y) {}
-Point() {};
6 Point& operator=(const Point& p) {
d_x = p.d_x; d-y = p.d-y; return *this; }
void setX(int x) { d~x = x; }
3 v0 i d .set Y( i nt y) { d-y = y; }
i nt x () con s t { ret urn d_x: }
int y() const { return d-y; }
o CD };
o 2 4 6 8 10
I!endif

(a) Set of Points (b) Header for Simple poi nt Component

Figure 5-59: Using Function qsort to Sort a Collection of Poi nt Objects

section 5.7 Callbacks 277

The qsort function rearranges entries by blindly swapping one region of memory of
the specified element size with another, based solely on the value returned from the
callback function. The bitwise copy is performed using a function such as the C
Library function memcpy.

In general, copying objects to new locations using memcpy is dangerous (see Section
10.4.2), because an object may contain a pointer or reference to itself or to other
objects which it is responsible for deleting. On the other hand, it is always safe to
copy and move pointers to objects using memcpy. Suppose we create an array of six
pointers to Poi nt objects and in it store the addresses of six Poi n t objects represent-
ing the points in Figure 5-59a.

static Point aCO,15), bC2,12), c(4,9), d(6,6), e(S,3), feIO,D);

static Point *array[6] = { &a, &b, &c, &d, &e, &f };

In order to use qsort, we wi~l need to give qsort away to compare two opaque
entries so it can determine their relative order. That is, given the addresses of a pair of
pointers to points (of type const voi d *), we need a way of determining whether the
distance from the origin to the Poi nt indicated by the first memory address is less
than, equal to, or greater than that of the Poi nt indicated by the second address. An
imperfect implementation of this callback function that suits our immediate needs is
given in Figure 5-60. 13

static int pointCompare (const void *addrPointIPtr,

const void *addrPoint2Ptr)
{
II poor implementation
const Point &pl = **(const Point **) addrPointlPtr;
canst Point &p2 = **(const Point **) addrPoint2Ptr;
int dlsq = pl.x() * pl.x() + pl.y() * pl.y(); II bad idea (overflow?)
int d2sq = p2.x() * p2.x() + p2.y() * p2.y(); II bad idea (overflow?)
return d2sq - dlsq;
}

Figure 5-60: Implementation of Callback Function Comparing 1\vo Poi n t Objects

13 A better implementation in practice would be to use a daub1e for the intermediate calculations, in order
to avoid overflow. This solution is implementation dependent, and may fail on two points that are placed
nearly the same (large) distance from the origin. A robust but less runtime-efficient solution would be to
make use of a user-defined type (e.g., Daub 1e I nt) that is guaranteed to hold at least twice as many bits as
an i nt.
278 Levelization Chapter 5

Programmed with the data indicating the starting location, number of entries, size of
each entry, and a callback function that determines the ordinal positions of two entries
in context, we can reuse this modular implementation of the Quicksort algorithm to
solve our problem as shown in Figure 5-61.

II point.t.c
#include "paint.h"
#include <stdlib.h> II qsort()
#include <iostream.h>

static int paintCornpare (const void *addrPointIPtr,

const void *addrPoint2Ptr)
{
II better (more practical) implementation
const Point &pl = **(canst Point **) addrPointlPtr;
canst Point &p2 = **(const Point **) addrPoint2Ptr;
double dlsq - pl.xC) * (double) pI.xC) + pl.y() * (double) pl.y();
double d2sq - p2.xC) * (double) p2.xC) + p2.yC) * (double) p2.y():
return d1sq < d2sq ? -1 : dlsq > d2sq; II Warning: may fail on
II points far from origin.

static ostrearn& operator«(ostream& 0, const Point& p)

{
, ,
return 0 « '(' « p.x() « « p.yC) « ')';
}

static ostream& printCostream& 0, const Point *const *array. int size)

{
o « '{';
for Ci nt i-a; i < s i z e; ++ i) {
o « ' , « *array[i];
}
return 0 « " }";
}

const int SIZE = 6;

static Point a(O,15), bC2,12), c(4,9), dC6,6), e(8,3), f(IO,O);

static Point *array[SIZE] = { &a, &b, &c, &d, &e, &f }:

rna i n ( )
{
print(cout, array, SIZE) « endl;
cout « "Now sort by distance from origin:" « endl;
qsort(array, SIZE, sizeof *array, pointCompare);
printCcout, array, SIZE) « endl;

Figure 5 ..61: Using a Callback to Program qsort Comparison Behavior

section 5.7 Callbacks 279

Realize that q s art was developed, tested, and reused many, many times, long before
the Poi n t class or this example was written. Most of the work done by the Quicksort
algorithm is reusable. Only one behavior, campa re, varies from one usage to the next.
Supplying a callback is what enables us to factor and reuse this functionality.

The indiscriminate use of callbacks can lead to designs that are

difficult to understand, debug, and maintain.

The lack of type safety in the interface of q s art is glaring. But because q so r t is a
stateless algorithm with a single programmable behavior, the need for a generic sorter
object is controvertible. There is, howev~r, an implied data structure. If we have rea-
-'

son to maintain a variety of ordered Poi n t collections, sorted according to various

comparison routines, then creating an abstract 0 rde red Po i ntCo 11 ect i on base class
(see Figure 5-62) with a corresponding iterator would prove generally useful. Doing
so would also catch most type errors at compile time.

class OrderedPointCollection {
I I ...
public:
II CREATORS
OrderedPointCollection();
virtual '-OrderedPointCollection();

II MANIPULATORS
void add(Point *point);

private:
II ACCESSORS
virtual int compare(const Point& pointl, const Point& point2) = 0;
};

Figure 5-62: Abstract Base Class for an Arbitrarily Ordered Point Collection

Specifying the comparison function is accomplished by deriving a simple s t rue t:

struct MyPoints : OrderedPointCollection {

compare(const Point& point, canst Point& point);
~MyPoints(); II empty -- (see Section 9.3.3)
};
280 Levelization ChapterS

We can now override the comparison function in a type-safe manner as follows:

int MyPoints::compare(const Point& pI, canst Point& p2)

{
II better (more robust) implementation
DoubleInt pIx = pl.x(); II Doublelnt is a type
Doublelnt ply = pl.y(); II that is at least
Doublelnt p2x = p2.x(); II twice as big as into
Doublelnt p2y = p2. y ( ) ;
Doublelnt dlsq = pIx * pIx + ply * ply; II robust but slow
Doublelnt d2sq = p2x * p2x + p2y * p2y; II robust but slow
return dlsq < d2sq ? -1 .. d1sq > d2sq; II robust but slow
}

The levelization of this system is shown in Figure 5-63. Notice that the class
OrderedPaintCollection depends on Point in name only, but MyPoints: :compare
depends on Poi nt in size. The virtual function is acting as a "callback" because the
comparison operation must be performed in the context of the Poi nt's actual defini-
tion. Unlike the callback function taking two generic pointers, the virtual function
expects canst references to Poi nt objects. This in-name-only dependency of
Or de red Poi nteo 1 1 e c t ion on Pa i n t provides a welcome degree of type safety,
improving maintainability while making the component easier to use.

Level 2: MyPoints

Levell:

In Name Only

Figure 5-63: Using a Virtual Function as a Callback to Enable Factoring

Callbacks are powerful decoupling tools, but they should be used only if necessary. A
mutual dependency generated by a pair of classes that call each other's member func-
tions is a symptom of a poor -design. Callbacks can sometimes be used to break the
cycle, but usually this problem is better handled by repackaging the functionality.
Section 5.7 Callbacks 281

Consider again the original, poorly factored, runtime database architecture shown in
Figure 5-27. If the read function of each parser implements a stateless algorithm, we
could conceivably pass the parsing function to the Runt i meDB as a callback:

RuntimeDB: :Status RuntimeDB::read(

RuntimeDB: :Status(*parseFunc)(const char *).
canst char *filename);

However, the resulting obfuscation would probably be unjustifiable. Unlike the previ-
ous example where OrderedPoi ntColl ecti on did not depend in size on Poi nt, each
concrete parser would have to know all about the database in order to load it. If parsing
involves state and/or a multifunction interface, the standard object-oriented approach
would be to create an abstract parser base class and to derive concrete parsers for use
with specific formats, as illustrated in Figure 5-64.

Figure 5-64: Demoting the Interface to Implement a Callback

This alternative revised architecture is better than the parser design as first presented
in Section 5.3, because there is no physical coupling among individual parsers, nor is
there a dependency of any processor on any parser implementation. However, this
architecture is not optimal because it forces the runtime database to know about the
interface common to all parsers:

#include "parser.h"

RuntimeDB::Status RuntimeDB::read(Parser *parser, canst char *filename)

{
parser-)read(this, filename); II virtual function call
}
282 Levelization ChapterS

The runtime database may be reused by other systems that have no need for parsers.
Coupling the runtime database to a specific parser interface unnecessarily encumbers
the subsystem, making it less general, less understandable, and less appealing to reuse.
This unnecessary coupling could also adversely affect the maintainability of the runtime
database if the kind of information needed during parsing is frequently updated.

The best design for this system was the revised architecture presented in Figure 5-29 of
Section 5.3, which placed the database at the bottom of the system hierarchy with
absolutely no dependency on parsers. That architecture allowed the database group to
develop and test its subsystem in complete isolation, rather than being sandwiched
between the interface and the implementation supplied by the group developing pars-
ers. The moral of this story is that the unnecessary use of callbacks is something to be
avoided.

Callbacks can also be installed statical1y (i.e., outside of any instance). The new han-
dler 14 is an example of a static callback function with reasonable initial behavior. Cli-
ents can substitute their own function for the default in order to allow them to clean up
their application in a higher-level context.

The need for callbacks can be a symptom of a poor overall architecture.

Sometimes, however, static callbacks can be used to great advantage to eliminate

dependencies on large subsystems. Consider the subsystems shown in Figure 5-65,
where we need to implement a heterogeneous list of planets-that is, a list of objects
that are related to the base class P1an e t via inheritance. Since the list is polymorphic,
each link cannot have a P1 a net but must instead hold (the address of) a P1 an e t. The
actual Pl anet object is allocated dynamically by the client and handed over to the
list, which assumes ownership of the Pl anet's memory from then on. When the
P1 an e t Lis t is destroyed, so are all of the P1 an e t objects it contains.

14 stroostrup, Section 9.4.3, pp. 312-314.

section 5.7 Callbacks 283

CCD = 30,005
(orCeD = 5)

class SolarSystem {
Star d_sun;
PlanetList d_list;
I / ...
};

\.
\.

\.

If this . ndency ) ~i"X~~~_~·•·• • ·• • • ·• il Link Cost = 10,000

(
were Just
In Name Only
class PlanetList {
/ I ....
public:
Pl anetL i st();
--Pl anetL i st();
void addPlanet(Planet *newPlanet);
II list now owns memory of newPlanet
II ...
};
solar system subsystem

planet subsystem

Figure 5-65: A BIG Problem

284 Levelization Chapter 5

As you might well imagine, P1 a net is a very large and complex base class object with
many dependencies and a correspondingly high link-time cost. We would like to avoid
a physical link-time dependency of Pl anetl i st on Pl anet, especially in this (admit-
tedly unusual) case where So 1 a rSy s tern otherwise depends on P1a net in name only.

We could try to implement the Pl anetL i st using only opaque pointers to Pl anet
objects. The problem with that approach is that our P1 an e t Lis t will not have seen the
definition of class P1 a net and therefore will not know how to destroy one. We could
change the specification of P1 an e t Lis t so that it does not itself destroy the planets,
and escalate that functionality to a higher level (e.g., Sol a rSystem) as suggested in
Figure 5-66.

class SolarSystem {
Star *d_sun_p;
PlanetList d_list;
static void destroyPlanets(PlanetList *list);
// ...
public:
// ...
~SolarSystem() { destroyPlanets(&d_List); }
// ...
};

Figure 5-66: Escalating Planet Destruction to a Higher Level

But in our example, even Sol a r Sy stem uses P1 an e t in name only. Since the use of the
Pl anetL i st type is an encapsulated implementation detail of Sol arSystem, it is not
obvious how to escalate this functionality any higher.

With complete control over the entire subsystem, a good solution could be to demote the
interface of P1 an e t, as shown in Figure 5-67. Now P1 an e t is just an interface, and all of
the physical coupling is elevated to a higher level that does not affect Sol arSystem.
Testing P1 an e t Lis t will now require deriving a trivial "stub" implementation for
P1 a net in the P1a net Lis t driver.
section 5.7 Callbacks 285

CCD=8

In Name Only

~~~.··...· •.. • 'i .•1 Link Cost = 10,001

bW •.. .•.•. . • ? ...............

\
\
\

solar system subsystem

planet subsystem

Figure 5-67: Demoting Pl anet's Interface to a Lower Level

Unfortunately, we don't control the universe and must live with a poorly factored
Pl anet. We can still break the physical dependency but it will require the use of a
redundant callback function. Suppose we add a static member to class P1 an et Lis t of
the following type:

typedef void DestroyPlanetFunc(Planet *);

286 Levelization Chapter 5

The P1a net Lis t class now has a static data member that is a pointer to a callback func-
tion that potentially has the necessary context to destroy an instance of class Pl anet.
Before using a P1 an e t Lis t for the first time, a client (who knows about P1 an e t) should
"prime" the class by calling the static method Pl anet Lis t: : setDes t royPl a net Func
with the address of a suitably defined function as shown in Figure 5-68. When the
P1 a net Lis t is destroyed, it can then call the des t roy P1 a net function on each planet
that it owns.

II client.c
#include "client.h"
lIinclude "planet.hl!
#include "planetlist.h"
I I ...
static void destroyPlanet(Planet *p) { delete p; }
I I ...
Client::initC)
{
PlanetList::setDestroyPlanetFunc(&::destroyPlanet);
II
};
II

Figure 5-68: Installing a Redundant Callback

A rough sketch of the relevant portions of the p 1 a net 1 i s t component is given in Fig-
ure 5-69. Class P1 an e t Lis t provides a mechanism for a client at a higher level to
install the callback function to destroy a P1 an e t. When a P1 an e t Lis t is destroyed,
the destructor checks to see if a destroy function has been installed, and if so applies it
to each P1 an e t in the list in tum. If no callback function has been installed by the time
the Pl anetL i st is destroyed, the contained Pl anet objects are not destroyed and the
dynamic memory associated with each Pl anet is "leaked." (Memory leaks are dis-
cussed in Section 10.3.5).
Section 5.7 Callbacks 287

II planetlist.h
I I ...
class PlanetListlter;
class PlanetList {
/ I ...
friend PlanetListlter;
public:
typedef void DestroyPlanetFunc(Planet *);
private:
static DestroyPlanetFunc *d_destroyPlanetFunc_p;
public:
static void setDestroyPlanetFunc(DestroyPlanetFunc *func);
I I ...
""'PlanetList ();
I I ...
};
II
class PlanetListlter {
I I ...
public:
PlanetListlter(const PlanetList &list);
""'PlanetListlter();
void operator++();
operator const void *() const;
const Planet& operator()(). const;
}; ,
/

I I ...

II planetlist.c
#include "planetlist.h"

PlanetList::DestroyPlanetFunc *PlanetList::d_destroyPlanetFunc_p - 0;

void PlanetList::setDestroyPlanetFunc(DestroyPlanetFunc *func)

{
d_destroYPlanetFunction_p _ func;
}

void PlanetList: :""'Pl anetList()

{
if (d_destroyPlanetList_p) {
for (PlanetListlter it(*this); it; ++it) {
(*d_destroyPlanetList_p)(it());
}
}
else {
II memory leak!
}
}

Figure 5-69: Using Callbacks to Enable Independent Testing

288 Levelization Chapter 5

U sing callbacks in this way is not the least bit elegant. Using P1 an e t Lis t requires
knowing about low-level details with which a client should not be bothered. This
approach is not recommended for public interfaces, as it can be assumed that people
will forget to initialize the container class before they use it. To make matters a bit
worse, P1 an et Lis t is not in the public interface of So 1 a rSy s tern. It will therefore be
necessary for So 1 a rSy stem to provide a static member such as

class SolarSystem {
// ...
public:
static void init(void (*)(Planet *));
// ...
};

that must then forward the initialization call to the P1 an e t Lis t class.·-

To summarize the results of this section, a callback is a function that is supplied by a

client to allow a (usually) lower-level component to take advantage of a behavior that
requires a (usually) higher-level context. Virtual functions can be used to implement a
type-safe callback mechanism. Callbacks are a powerful tool for breaking dependen-
cies between cooperating classes. Callbacks are extremely important for graphics and
event-based programming.

Used inappropriately, callbacks can blur the responsibility of low-level objects and
result in unnecessary conceptual coupling. In general, callbacks (like recursion) can
be more difficult to understand, maintain, and debug than conventional function calls.
Their (pseudo) asynchronous behavior requires a different type of attention from
developers. As a rule, callbacks should be treated as a refuge of last resort.

5.8 Manager Class

In the name of minimizing complexity and effort, it is easy to become too frugal with
classes. Trying to implement an integer list with only a single class is a good illustra-
tion of this common mistake. One might suggest, as in Figure 5-70a, that a list could
be just a pointer to aLi n k or, as in Figure 5-70b, that the link operations could be
merged with the methods associated with the List itself.

The problem with approach (a) is that the level of abstraction is too low for an appli-
cation to use effectively. Approach (b) fails to encapsulate private implementation
details of Lis t. Clients of a list abstraction will not want to be bothered with the low-
section 5.8 Manager Class 289

level details of managing the memory of the individual links, or with ensuring that the
low-level policies of a list implementation are enforced.

(a)
Li nk* ...--....ott> - C> -- o
int int int
Link Link Link

o
(b)
? int int int
List List List List
Figure 5-70: How Not to Implement ali 5 t Component

Even in a two-class list architecture, the role of the subordinate class can be abused.
Normally, a list object itself destroys each of its links directly, but as shown in Figure
5-71, the destructor for this Lis t deletes only the head Lin k. Each Lin k, in tum,
recursively deletes its d_next_p pointer. This "elegant" approach (apart from being
slower and running the risk of overflowing the program stack for long lists) makes it
less clear which object owns which, primarily because instances of the same type are
authorized to destroy one another. A better, more hierarchically structured way for the
Lis t class to clean up when it is destroyed.is to traverse the list of Lin k objects and to
delete each Lin k in turn, as shown in Figure 5-72.

class List { class Link {

Link *d_head_p; Link *d_next_p;
int d_data;
public: public:
I I ... I I ...
,. . Lis t () { del e t e d_ he ad_p; } ~Link() { delete d_next_p; }
I I bad idea II bad idea
I / ... I I ...

Figure 5-71: Lis t with Lin k that Recursively Deletes the Next Lin k
290 Levelization Chapter 5

List: :'"'"'List()
{
while (d_head_p) (
Link *p = d_head_p;
d_head_p = d_head_p->next();
delete p;
}
}

Figure 5-72: List with Destructor that Iteratively Deletes Each Link

Establishing hierarchical ownership of lower-level objects makes a

system easier to understand and more maintainable.

Again the corporation analogy pertains. Regular employees do not hire and fire each
other; that job is reserved for managers. The intrinsic problem is in not distinguishing
between the classes used to implement an abstraction and the manager class used to
enforce policy, manage memory, and coordinate the implementation classes. Note that
the manager class knows about its subordinate classes, but not vice versa.

All too often the cyclic interconnection among instances of classes seems to suggest
that this cyclic nature should be reflected in the physical design of a system. For small
cyclicly dependent networks of objects that are inherently tightly coupled and whose
definitions fit easily within a single component, there may be no reason to eliminate
such cycles. That is, if it makes sense from a standpoint of usability and reuse to
present two or more cohesive logical units in a single physical unit, and the functional
complexity of the combined implementation does not pose an obstacle to effective
testing, then there may be no problem that requires solving. On the other hand, the
coupling may also be the result of not knowing how to avoid the interdependenc~es, or
of not even having considered the issue in the first place.

As another example where the concept of a manager class proves useful, consider a
simple graph consisting of nodes and edges. A graph is among the most basic of het-
erogeneous class networks; yet a node could be as complex as a workstation on a
local area network (LAN), or a planet in a solar system. In other words, the size and
complexity of the graph-independent portion of the node and/or edge might be very
section 5.8 Manager Class 291

large compared to its network-related aspects. It is in these cases that there is consid-
erable motivation to decouple nodes from edges.

Let us start with the situation suggested by Figure 5-10. We can illustrate the princi-
ples related to achieving a levelizable interconnected network of heterogeneous
objects by attempting to develop a simple graph with the premise that Node and Edge
are complex and should belong to distinct physical components.

A known effective technique for avoiding cyclic physical dependencies is to make all
pointers and references to higher-level components be in name only. Perhaps we can
concoct a levelizable subsystem in which edge dominates node. Our strategy will be
to have Node hold a collection of opaque Edge pointers, as illustrated in Figure 5-73.
Taking this approach means that all substantive questions that involve edges cannot be
answered at the node level.

Level 2:
In Name Only

Levell:

Figure 5-73: Node Uses Edge In Name Only

In the process of trying to test component n ad e independently, we immediately realize

some problems (refer to Figure 5-74). First, clients must not add Edge pointers to a
Node directly. Otherwise the Node object would know about the newly added Edge but
the Edge object would remain ignorant of its new connection to a Node, leaving the
system in an inconsistent state. Therefore, only Edge objects are allowed to add an
Edge pointer to a Node, but there is no way to enforce this policy with Node and Edge
defined in separate components (see Section 3.6.2).

Second, testing Node requires creating a dummy Edge class in order to gain access to
the private addEdge function-that is, we are not able to test Node from its intended
public interface alone.
292 Levelization ChapterS .'

class Node {
I I ...
friend Edge; II long-distance friend
. void addEdge(Edge *edge); II private, set only by edge
.,/ Node (const Node&);
Node& operator=(const Node&);

public:
Nade(const char *name); II Who owns the memory for nodes?
-Node ( ) ; II Who is allowed to destroy them?
canst char *name() canst;
int numEdges() canst;
Edge& edge(int index) const; II Reference hampers testing slightly
}; II since Edge is used in name only.

Figure 5-74: Problems Associated with Original Graph Design

Third, the Node's edge function is correctly designed (from the end-user perspective)
to return, references and not pointers. A reference (even an opaque one), unlike a
pointer, must identify the address of a valid object and therefore cannot (portably) be
null or refer to an illegal address. So if we ask for an Edge of a newly created Node
(which has no edges) we are in trouble. Incrementally testing Node's public edge
function at the node component's level requires not only creating a dummy Edge class
to gain access to the private add Ed ge function of Nod e, but also adding actual
instances of this bogus Edge class so that their (valid) addresses can be compared later
against the lvalues returned by edge (i nt).

Finally, it is not clear who owns the memory for Node instances or who is allowed to
create and destroy them. For example, what happens if we try to destroy a Nod e before
we have removed all of its edges? The answer is that nothing unusual happens-at
least not right away_ Since Node does not know about Edge, it does not know how to
destroy one. Using an Ed ge to access a deleted Nod e will, of course, result in unpre-
dictable behavior. We could pass a callback function to Node that knows how to delete
an Edge, but then we must ensure that Edge objects are created only on the heap.

At this point our design has run out of steam. As often happens in practice, we need to
step back and look at the abstraction we are trying to implement, namely a graph. Just
as with rectangl e and wi ndow, neither node nor edge inherently dominates the other.
There is a mutual dependency involving ownership, which we need to escalate to a
higher level of the system.
Section 5.8 Manager Class 293

Figure 5-75 shows the basic architecture of the new design that will serve as a sound
starting point. Class Grap h will be responsible for managing the memory associated
with instances of both Edge and Node. Nodes and edges will be added to the graph
through Grap h 's interface, as opposed to creating them independently. When a Nod e is
deleted from the graph, Grap h itself will ensure that all Ed ge objects attached to that
Node will be deleted first. This basic design still suffers from the problem that both
Node and Edge must declare Graph to be a fri end. Otherwise unruly clients could, for
example, add an Edge to a Node unbeknownst to either the Edge or the Graph, causing
the graph subsystem to become internally inconsistent. Since we want Node and Edge
to be defined in separate components, we are still not satisfied.

Level 2:

Levell:

In Name Only

Figure 5-75: Basi~ Architecture of Graph Subsystem

.,

For a simple graph, it may be entirely reasonable to place all three classes within a
single component. But because our goal here is to use the graph to illustrate how to
implement much more complex networks, we will not take that approach. There are
(at least) two other ways to address this problem:

1. Factor out as much code as possible from the coupled system into inde-
pendent components, and place the remaining, mutually dependent
classes in a single component.

2. Escalate the level at which encapsulation for the entire subsystem occurs
to eliminate the need for low-level friendships~~/

Each of these techniques is discussed in detail in the following two sections.

294 Levelization Chapter 5

In summary: establishing clear ownership of cooperating objects is essential to good

design. If two or more objects share mutual ownership, that functionality should be
escalated to a manager class.

5.9 Factoring

Factoring means extracting pockets of cohesive functionality and moving them to a

lower level where they can be independently tested and reused. Factoring is a very
general and highly effective technique for reducing the burden imposed by cyclicly
dependent classes. Factoring is similar to. demotion except that the act of factoring
does not necessarily eliminate any cycles; instead it merely reduces the amount of
functionality that participates in the cycle. Factoring has the effect of escalating cyclic
"

dependencies to a higher level where their adverse effects are less pronounced.

To demonstrate the use of factoring, suppose we are given a design consisting of three
intrinsically interdependent classes A, B, and C, as illustrated in Figure 5-76a. Suppose
further that the original logical interface is cast in stone and may not be modified.
More than likely, not all of the functionality implemented in these three classes is
inseparably coupled to the rest. We can use the technique of factoring to extract any
independently testable implementation complexity, and thus reduce the burden of
maintaining the truly cyclicly dependent portion of the code. As illustrated in Figure
5-76b, if we are successful in factoring a significant amount of the implementation
into independent components, the remaining interdependent code may be small
enough to justify placing it into a single component.
section 5.9 Factoring 295

(a) Original, Unlevelizable Design (b) Factored, Levelizable Design

Figure 5-76: Factoring Out Independently Testable Implementation Details

Factoring out and demoting independently testable implementation

details can reduce the cost of maintaining a collection of cyclicly
dependent classes.

Fortunately, our graph example is less extreme than the hypothetical case above. We
have some flexibility in our logical design, and it will turn out that the implied physi-
cal dependencies are not as severe as the hypothetical ones we are postulating. For
now, let us continue to assume the worst-that is, that our initial graph subsystem is a
design consisting of three intrinsically, mutually dependent classes:

Graph

Node Edge
296 Levelization ChapterS

The first place to employ factoring is to separate the part of Nod e that holds graph-
related ,data from the part of Node that holds graph-independent data. Inheritance is
ideal for this kind of factoring. We can do the same for Edge. The basic idea is shown
in Figure 5-77.

Level 2:

Levell:

node edge

Figure 5..77: Factoring Out Network-Independent Data

In this new design, all of the tightly coupled, graph-related functionality lives in a sin-
gle component, implemented using the three classes Graph, Gnode, and Gedge. The
graph-independent data contained in Node and Edge is now pushed down to a lower
level, and can be shared with other applications that are not concerned with the graph-
related functionality.

Figure 5-78 illustrates the factored, network-independent portions of node and edge.
In this trivial illustration a Node is nothing more than a name, and an Edge is just a
do U b 1e. But suppose for a minute that the nodes in the graph are actually cities and
the edges are roads. The network component of a city, implicit in Gnode, is not neces-
sary to perform many complex operations on a Node itself. A Gnode is just a special
kind of Node that participates in Graph operations. Once an instance of Gnode has
been obtained from Graph, it can be used anywhere in which a Node is required, as
illustrated in Figure 5-79.
section 5.9 Factoring 297

// node.h /1 edge.h
#ifndef INCLUDED NODE #ifndef INCLUDED_EDGE
#define INCLUDED_NODE #define INCLUDED_EDGE

class Node { class Edge {

char *d_name_p; double d_weight;

public: public:
Node(const char *name); Edge(double weight);
NodeCconst Node&); EdgeCconst Edge&);
-Node(); ~EdgeC) ;
Nod~& operator=Cconst Node&); Edge& operator=(const Edge&);
const char *nameC) const; / double weight() const;
}; };

#endif #endif

(a) Independent node Component (b) Independent edge Component

Figure 5-78: Factored Network-Independent node and edge Components

class Node;
class ostream;

class Census {
static int countPeople (const Node& node)
I I ...
};

#include "graph.h"
int g(const Gnode& gnode)
{
return Census::countPeopleCgnode); II uses only the Node portion
}

Figure 5-79: Reusing the Network-Independent Portion of a Node

Another advantage in factoring nodes and edges involves a concept called value
semantics. Saying that a type has value semantics means that a copy constructor and
(usually) an assignment operator are inherently (Le., semantically) valid operations
for a type. 15

/' ... -'

15Sometimes we choose not to implement a copy constructor (e.g., for an iterator) even when the
operation could make sense; however, the abstraction itself has value semantics.
298 Levelization ChapterS

For example, consider a condominium complex that contains a fixed amount of land
on which to build single-family homes. The land is divided into 25 lots, arranged in a
5-by-5 grid. The rows of lots are labeled A to E, and the columns are labeled 1 to 5 as
shown in Figure 5-80.

E~O 0 0 0 Model Home

D~O 0 0
C~O 0
B
000
o
1 2 3 4 5
CondoComplex

Figure 5-80: Array of 25 Lots in our CondoComp 1 ex Example

Each Lot is a separate object that maintains its own list of adjacent lots and is man-
aged by the CondoComp 1ex object. For example, Lot A2 holds pointers to Lot objects
AI, B2, ~nd A3. A House has value semantics because copy construction makes sense
for a House. In other words, it makes sense to copy a House from Lot to Lot-that is,
all houses could look exactly the same.

Suppose now that a Property consists of both the House and the Lot on which it sits,
and that the CondoCompl ex object manages an array of Property objects instead of
Lot objects. Does a Property.. also have value semantics? The answer is no, because
we cannot copy one lot to another.

If we tried to assign the Property with Lot location A2 to the Property with Lot
location C4, we would clobber the adjacency list associated with Lot C4 and invali-
date the larger CondoComp 1 ex object. We therefore cannot make arbitrary independent
Section 5.9 Factoring 299

copies of a Property the way we can for a House. A Property therefore does not
have value semantics.

Although the network portion of a node (defined by Gnode) does not have value
semantics, the part that is defined by Nod e probably does. In C++ terms, this means
- that the copy constructor and assignment operator of both Gnode and Gedge would
necessarily be disabled (i.e., declared private), but Node and Edge could each define
meaningful copy constructors and assignment operators, as shown in Figure 5-81.
(The complete interface for graph is given in Figure 5-86.)

void fCconst Graph& g)

{
const Gnode& a = g.node("Zurich"); II fine - lvalue returned
Gnode b = g.nodeC"London"); II error - no value semantics
Node& c = g.node("Paris"); II fine - modifiable lvalue returned
Node d = g.node("Tokyo"): II fine - value semantics
a = b: II error - no value semantics
c = d; II fine - make Tokyo look like Paris
}

Figure 5-81: Illustrating Value Semantics in a Graph

Where unavoidable, escalating cyclic physical dependencies to the

highest possible level reduces CCD and may even enable the cycle to
be replaced by a single component of manageable size.

Our second opportunity to factor comes from the observation that, in order to manage
Node and Edge objects properly, Graph will need to keep track of the Gnodes an Gedge
objects it allocates so that when it is destroyed, all of the memory associated with
the nodes and edges of this graph can be recovered. Moreover, each Gnode will also
have to keep track of the Gedge objects adjacent to it (in name only). We have the
opportunity to factor out all of this functionality from the graph component classes
by creating a collection of opaque pointers.

A bag is a kind of container that, unlike a list, does not impose an order on its ele-
ments nor, unlike a set, does it require elements to be unique. Because the semantics
300 Levelization Chapter 5

of a bag are not heavily specified, its implementation is left quite flexible. A Graph
will maintain a bag of Node pointers and a bag of Edge pointers. Whether or not We
have an efficient template implementation, we will want to factor this problem further
by creating a bag of (generic) pointers.

Figure 5-82 shows our factored implementation of a generic bag of pointers and Spe-
cialized components that take advantage of this generic container to implement bags
of pointers of a specific type. We can use either layering or private inheritance to
achieve the desired specialization and restore the type safety of the individual opaque
pointers. Templates would be ideal, but some implementations can be very costly in
terms of link time (as discussed in Section 10.4.1). For purely pragmatic reasons we
may be forced to express the specialized types explicitly. Whatever the implementa-
tion, all of the function arguments are forwarded to the generic Pt r Bag class via
i n 1 i ne functions in order to avoid incurring any additional overhead due to conven-
tional function calls.

gnodeptrbag gedgeptrbag

ptrbag

Figure 5-82: Generic PtrBag Container and Specializations

Figure 5-83 shows the header for a ptrbag component, consisting of four classes.
Pt rBa 9 Lin k is a low-level implementation class whose use is an encapsulated
section 5.9 Factoring 301

implementation detail of the other three classes in the p t r bag component. We could
instead have placed PtrBagLink in a separate component, defined it entirely within
the pt r bag. c file, or nested it within class Pt r Bag. (The advantages and disadvantages
of these and other similar design alternatives are compared and discussed in Section
8.4.)

II ptrbag.h
#ifndef INCLUDED_PTRBAG
#define INCLUDED_PTRBAG

class PtrBaglter;
class PtrBagManip;

class PtrBagLink {
void *d_pointer_p;
PtrBagLink *d_next_p;

private:
PtrBagLink(const PtrBagLink&);
PtrBagLink& operator=(const PtrBagLink&);

public:
PtrBagLink(void *pointer. PtrBagLink *next);
---PtrBagLink();
PtrBagLink *&nextRef(); II used by manipulator
'PtrBagLink *nextC) const;
void *pointerC) const;
};

class PtrBag {
PtrBagLink *d_root_p;
friend PtrBaglter;
friend PtrBagManip;

private:
PtrBagCconst PtrBag&);
PtrBag& operator=(const PtrBag&);

public:
PtrBag();
. . . PtrBag();
void add(void *pointer);
void removeAll(const void *pointer);
};

class PtrBagIter {
PtrBagLink *d_link_p;
302 Levelization Chapter ~

private:
PtrBaglter(const PtrBaglter&);
PtrBaglter& operator=(const PtrBaglter&);

public:
PtrBaglter(const PtrBag& bag);
""'PtrBaglter();
void operator++();
void *operator()() const;
operator const void *() const;
};

class PtrBagManip {
PtrBagLink **d_addrLink_p;

private:
PtrBagManip(const PtrBagManip&);
PtrBagManip& operator=(const PtrBagManip&);

public:
PtrBagManip(PtrBag* bag);
---PtrBagManip();
void advance();
void remove():
void *operator()() const;
operator const void *() canst;
}:

II inline function definitions omitted

#endif

Figure 5·83: Header File for Generic ptrbag Component

Pt r Bag is a container used to hold generic pointers. For this application, a redundant
but convenient member function is supplied to remove all pointers with the specified
value from the Pt rBa g. Pt rBa 9 I te r is part of the logical abstraction of a bag of point-
ers, allowing clients to iterate over the bag, returning its contents in some unspecified
order. Pt r Bag Man i p is similar to Pt r Bag I t e r except that it allows its client to modify
the bag by selectively removing entries-a capability punctuated by requiring the client
to supply the address of the container to be manipulated.

Most of the functions declared in p t r bag. h would probably be implemented inline,

simply because the size of the code they ge~erate inline is smaller than that of a func-
tion call. The few exceptions are implemented out of line, as shown in Figure 5-84.
The destructor for PtrBag as well as the removeA 11 function have loops, making
section 5.9 Factoring 303

them poor candidates for inlining. The add function accesses the global free store, so
it is useless to try to inline it for speed purposes. The remove function consists of
enough code that calling a function will probably produce less object code than sub-
stituting the source in place. While the remove function call adds some execution
~

overhead, removing edges is not expected to be a frequently executed function. After

performance analysis, the remove function is the only one of these four that stands a
chance of improvement by being declared i n1 i n e.

II ptrbag.c
#include "ptrbag.h"

PtrBag: :-PtrBag()
{
PtrBagManip man(this);
while (man) {
man.remove();
}
}

void PtrBag::add(void *pointer)

{

void PtrBag::removeAll(const void *pointer)

{
PtrBagManip man(this);
while (man) {
mane) == pointer? man.remove() man.advance();
}
}

void PtrBagManip::remove()
{
PtrBagLink *tmp = *d_addrLink_p;
*(PtrBagLink **)d_addrLink_p = (*d_addrLink_p)->next();
delete tmp;
}

Figure 5-84: Implementation File for Generic ptrbag Component

The component-dependency graph for the new subsystem is shown in Figure 5-85.
Look at all of the functionality that has been extracted from the cyclic group of
classes buried in the graph component. This functionality can now be tested and
reused independently of that cycle. The functionality in gedgeptrbag is reused in two
different ways even within the graph component itself: once in class Graph to keep
304 Levelization Chapter 5

track of all edges, and once in class Gnode to keep track of connected edges. At this
point we have reduced the amount of cyclicly dependent code to a manageable level
of complexity appropriate for a single component-g rap h. The complexity of the
graph-independent functionality identified by either Node or Edge is now segregated
into independent components, that are testable in isolation.

Level 3:

Level 2:

Levell: /

Figure 5-85: Component Dependency for a Factored Graph Architecture

Figure 5-86 gives the complete header file for the graph component. This implemen-
tation is efficient, flexible, and reasonably maintainable. However, using this compo-
nent is not so straightforward because some of the interface (along with the
implementation) has been factored out and placed in reusable components at lower levels.

II graph.h
#ifndef INCLUDED_GRAPH
#define INCLUDED GRAPH
#ifndef INCLUDED_NODE
#include "node.h"
#endif
#ifndef INCLUDED EDGE
#include "edge.h"
#endif
#ifndef INCLUDED_GNODEPTRBAG
#include "gnodeptrbag.h"
4Iendif
4Iifndef INCLUDED_GEDGEPTRBAG
#include "gedgeptrbag.h"
lIendif
class Graph;
Section 5.9 Factoring 305

class Gnode : public Node {

GedgePtrBag d_edges;
friend Graph:
Gnode(const Gnode&); II not implemented
Gnode& operator=(const Gnode&); II not implemented
private:
Gnode(const char *name):
---Gnode() ;
void add(Gedge *edgePtr):
void remave(Gedge *edgePtr);
public:
const GedgePtrBag& edges() const;
};
class Gedge : public Edge {
Gnode *d_from_p;
Gnode *d~to_p;
friend Graph;
Gedge(const Gedge&); II not implemented
Gedge& operator=(canst Gedge&); II not implemented
private:
GedgeCGnode,*from, Gnode *to, double weight):
---Gedge():
public:
Gnode *from() const;
Gnode *to() canst;
};
class Graph {
GnodePtrBag d_nodes;
GedgePtrBag d_edges;
GraphCconst Graph&);
Graph& operator=(const Graph&);
public:
Graph();
....,Graph ( ) ;
Gnode *addNode(const char *nodeName);
Gnode *findNode(const char *nodeName);
void removeNode(Gnode *node);
Gedge *addEdge(Gnode *from, Gnode *to, double weight);
Gedge *findEdgeCGnode *from. Gnode *to);
void removeEdgeCGedge *edge):
canst GnodePtrBag& nodes() const;
canst GedgePtrBag& edges() const;
};
lIendif

Figure 5-86: graph Component Header Defining Classes Gnode, Gedge, and Graph
306 Levelization Chapter 5

For example, suppose you wanted to iterate over the edges connected to a particular
node in a graph. You would need to get the bag of Gedge pointers from that Gnode and
then use that bag to construct an instance of EdgePtrBagIter:

int sumOfEdgeWeights(const Gnode& gnode)

{
i nt sum = 0; F''-'I,-

for (GedgePtrBaglter it(gnode.edges()); it; ++it) {

sum += itC)-)weight();
}
return sum;
}

Conveniently, the same methodology works for obtaining all of the edges and nodes
from the graph itself, as illustrated in the implementation of the output operator for a
Graph given in Figure 5-87.

ostream& operator«Costream& 0, canst Graph& graph)

{
cout « "Graph: « endl;
II

GnadePtrBaglter nit(graph.nodes());
if (nit) {
a «II Nodes: lI
;

}
for (; nit; ++nit) {
a <<" "< < nit ( ) - ) name ( ) ;
}
canst char *p =" Edges: " .,
canst char *q = II ";

for (GedgePtrBaglter eit(graph.edgesC)); eit; ++eit) {

o « endl « p « eit()-)fromC)-)name()
« " ___ (II « eit()-)weight() « ") __ ) "
« eit()-)ta()-)nameC);
p = q;
}
a « endl « IIEnd Graphll « endl:
return 0;
}

Figure 5-87: An operator« for Graph Using Low-Level Iterators

A test driver implementing the graph component of Figure 5-86 is given, along with
its output, in Figure 5-88. Notice that the Gnode pointers returned by both addNode
and fi ndNode point directly at the corresponding Gnode within the Graph. The only
publicly available function in Gnode, edges ( ), supplies a const reference to its bag of
Gedge pointers, which can then be used directly by the client to traverse the graph.
section 5.9 Factoring 307

The only public functionality available in a Gedge provides access to the two Gnode
objects to which the Gedge is connected .

// graph.t.e
#inelude "graph.h"
ifinclude "gnodeptrbag.h"
ifinelude "gedgeptrbag.h"
#include <iostream.h)

ostream& operator«(ostream& 0, const Graph& graph);

maine)
{
Graph g;
{
Gnode *nl - g.addNodeC"Mindy");
Gnode *n2 - g.addNode("Susan");
Gnode *n3 - g.addNode("Rick");

g.addEdge(n2, nl. 4);

g.addEdge(nl, n3, 5);
g.addEdge(n3. n2. 1);

g.addNodeC"Franklin");
g.addNode("Cathy");
}

g. addEdge( g. fi ndNode( "Susan"), g. fi ndNode( Frankl i nil), 6);

II

9 . add Ed9,e ( 9 . fin dNod e ( Ric k" ), g. fin d Nod e ( Fran k1 i nil), 2);
II II

g. addEdge( g. fi ndNode( Ri ck "), g. fi ndNode( "Cathy"), 3);

II

cout « g;

1-/ Output:
john@john: a.out
Graph:
Nodes: Cathy Franklin Rick Susan Mindy
Edges: Rick ---(3)--) Cathy
Riek ---(2)--) Franklin
Susan ---(6)--) Franklin -, ..

Rick ---(1)--) Susan

Mindy ---(5)--) Rick
Susan ---(4)--) Mindy
End Graph
john@john:

Figure 5-88: Simple Test Driver Illustrating Usage of the graph Component
308 Levelization Chapter 5

Granting friendship does not create dependencies but can induce

physical coupling in order to preserve encapsulation.

In this implementation of Grap h, private access via (local) friendship to Gnod e and
Gedge is essential to preserving encapsulation. This design eliminates the problems
associated with long-distance friendship by physically uniting the parts of the system
that need to share common implementation details via private access. In other words,
by combining Graph, Gnode, and Gedge in a single component, the required friend-
ships are no longer long-distance ones.

As illustrated in Figure 5-89, it turns out that Gnode and Gedge depend on each other
in name only, and have no backward dependency on Graph. Although the three classes
have no cyclic interdependencies, there is still a need for factoring. Clients of this sub-
system will need to interact directly with both Gnode and Gedge. Making the entire
interface of either Gnode or Gedge public would expose clients to implementation
details of the 9 rap h component. Worse, doing so would allow clients to violate impor-
tant policies enforced by the Grap h manager class.

Graph

In Name Only

Figure 5-89: Actual Relationships Among Graph, Gnode, and Gedge

For example, making the Gedge constructor public would allow clients to bypass the
Graph object and create instances of a Gedge on the program stack. There would be
section 5.9 Factoring 309

nothing to stop a wayward client from adding aGe d9 e created on the program stack to
a legitimate Gnode belonging to an otherwise valid Graph.

To avoid these problems it is necessary to grant class Grap h access to private function-
ality defined in both Gnode and Gedge. Avoiding long-distance friendship then forces
us to place these intimately dependent classes in the same component. Although there
is no direct physical dependency brought on by granting friendship, modularity and
encapsulation dictate the effective physical coupling suggested in Figure 5-90.

graph

Figure 5-90: Implied Physical Coupling to Avoid Long-Distance Friendship

The fact that the physical coupling is brought about only by friendship (as discussed in
Section 3.6) and not hard physical dependencies opens the door to another technique,
which we will explore in the next section. For completeness, the implementation file
for the graph component is provided in Figure 5-91.

To summarize the results of this section: factoring is a general technique that can be
used to reduce the maintenance cost of designs with inherent cyclic dependencies. By
relocating some of the implementation complexity to lower-level components, that
functionality can be tested (and possibly reused) independently of the remaining
cyclicly interdependent code. Factoring results in more flexible architectures without
sacrificing runtime efficiency. When factoring the interface of a subsystem, clients
may be asked to use component interfaces atlower levels of the subsystem hierarchy.
310 Levelization Chapters

II graph.c .
#include "graph3.h"
#include <string.h)
II -*-*-*-*- class Gnode -*-*-*-*-
Gnode: :Gnode(const char *name) : Node(name) {}
Gnode: : . . . Gnode () {}
void Gnode::addCGedge *edgePtr) { d_edges.add(edgePtr); }
void Gnode::remove(Gedge *edgePtr) { d_edges.removeAll(edgePtr); }
const GedgePtrBag& Gnode::edges() const { return d_edges;

II -*-*-*-*- class Gedge -*-*-*-*-

Gedge::GedgeCGnode *from, Gnode *to, double weight)
EdgeCweight)
, d_from_p(from)
, d_to_pCto) {}
Gedge: :---GedgeC) {}
Gnode *Gedge::from() const { return d_from_p; }
Gnode *Gedge: :toC) canst { return d_to_p; }

1/ -*-*-*-*- class Graph -*-*-*-*-

Graph: :Graph() {}
Gr a-p h : : ""' Grap h C)
{
for CGedgePtrBaglter eitCd_edges); eit; ++eit) {
delete eitC);
}
for CGnodePtrBaglter nitCd_nodes); nit; ++nit) {
delete nitC);
}
}

Gnode *Graph: :addNode(const char *nodeName)

{
Gnode *p = new Gnode(nodeName);
d_nodes.addCp);
return p;
}

Gnode *Graph::findNade(const char *nodeName)

{
for (GnodePtrBaglter it(d_nodes); it: ++it) {
if (0 == strcmpCit()-)name(), nodeName) {
return itC);
}
return 0;
}
section 5.9 Factoring 311

void Graph::r~moveNode(Gnode *node)

{
GnodePtrBagManip nodeMan(&d_nodes);
while (nodeMan) {
if (nodeMan() == node) {
for (GedgePtrBaglter it(nodeMan()-)edges()); it; ++it) {
d_edges. removeA 11 (i t ( ) ) ;
}
nodeMan.remove();
}
else {
nodeMan.advance();
}
}

Gedge *Graph: :addEdge(Gnode *from, Gnode *to, double weight)

{
Gedge *p = new GedgeCfrom, to, weight);
d_edges.add(p);
from-)addCp);
to-)add(p);
return p;
}

Gedge *Graph::findEdge(Gnode *from. Gnode *to)

{
for (GedgePtrBaglter itCd_edges); it; ++it) {
if (it()-)fromC) == from && it()-)to() == to) {
return it();
}
}
return 0;
}

void Graph::removeEdge(Gedge *edge)

{
GedgePtrBagManip edgeMan(&d_edges);
while (edgeMan) {
if (edgeMan() == edge) {
edge-)to()-)removeCedge);
edge-)fromC)-)remove(edge);
edgeMan.removeC);
}
else {
edgeMan.advance();
}
}
}

canst GnodePtrBag& Graph: :nodes() const { return d_nodes: }

const GedgePtrBag& Graph::edges() const { return d_edges: }

Fi2ure 5-91: graph. c Implementation File for graph Component

312 Levelization Chapter 5

5.10 Escalating Encapsulation

As a C++ programmer, you have no doubt encountered the notion of encapsulation.

An interface is encapsulating if it makes the details of its implementation program-
matically inaccessible to clients. A common misconception is that it is necessary for
each individual class or component to encapsulate all implementation details and
present a robust interface to the entire world. Doing so would make large, complex
subsystems intolerably larger, slower, and more complicated than need be. Instead we
can hide a number of useful low-level classes behind the interface of a single compo-
nent (as was the case with the p2p_router component in Chapter 4.) We will often
refer to such a component as a wrapper. 16

Figure 5-92a illustrates a subsystem in which each individual component presents a

public interface that is appropriate for direct use by clients in the context of using that
subsystem. The encapSUlation for this subsystem is enforced on a per-component basis.
Figure 5-92b shows a subsystem in which some of the components defined within the
subsystem are not exposed in the overall subsystem interface as defined by the wrapper
component, w. That is, none of the types defined in components u, v, or yare part of
either the pub 1 i c or protected interfaces of w. Although components u, v, and y are
individually available for use by anyone, there is simply no programmatic way even to
detect whether these components are used to implement w. Consequently, there is no
programmatic way to take any advantage of the objects defined in these components
when interacting with instances of this subsystem. The encapsulation for subsystem B
is enforced by the wrapper component at the highest level of the subsystem.

wrapper is a component-based implementation of a design pattern known as Facade in gamma,

16 A
Chapter 4, pp. 185-193.
section 5.10 Escalating Encapsulation 313

interface component

:f.:J>i:
................ :: .. :::.:.::: . .
implementation component
t..···· . 2:.L····Z·.i D

Clients of Subsystem A Clients of Subsystem B

I

• •
• •
• •
I

•
I
I

(a) Per-Component Encapsulation (b) Subsystem-Level Encapsulation

Figure 5-92: Spheres of Encapsulation

What is and what is not an implementation detail depends on the

level of abstraction within the physical hierarchy.

By analogy, a Spa rkPl ug is an implementation detail of Ca r, but Spa rkPl ug is used in

the interface of Engi ne, which is encapsulated by Ca r. At the level of abstraction that
is the inside of Car's subsystem, Spa r k P1 u9 is part of the public interface of the hier-
archy of components that make up the Ca r's implementation. At the level of abstrac-
tion of the Car's client, the Spa r k P1 u9 is hidden.
314 Levelization Chapter 5

When we use a low-level library component (such as qsort) in the implementation of

our subsystem, we do not think twice about how appropriate that component would be
in the hands of our client. Whether or not we happen to make use of q so r twill
remain an encapsulated implementation detail of our subsystem. We cannot stop our
clients from using qsort on their own; however, we can easily conceal whether or not
we make use of it ourselves. This same philosophy applies to components we define
within our subsystem.

Suppose that component y in Figure 5-92b defines the 0 r de red Poi n t Colle c t ion of
Section 5.7. Clients of our subsystem may have absolutely no need for ordered point
collections, yet this component is used by other components within our subsystem to
implement higher-level functionality. At the lower levels of a subsystem, components
will be exchanging correspondingly lower-level information. This information,
although it is an implementation detail to the end user, is well defined, predictable,
and appropriate for the interfaces of low-level components.

We could try to hide 0 rde red Po i ntCo 11 ect i on by making all of its interface func-
tions private and granting specific, higher-level components, such as u and v, friend
status-but why complicate matters? There is no harm a client can do with the defini-
tion of 0 r de red Poi n t C0 11 e c t ion so as long as this type is not used in the interfaces
of the components that define the overall interface to the subsystem. 17

The subsystem shown in Figure 5-92a is similar in structure to the factored implemen-
tation of the graph subsystem presented in the previous section. In that architecture
(Figure 5-85), clients were asked to make use of lower-level components (such as
ptrbag) in the normal course of using the subsystem.

An alternative implementation for a graph would be to provide a wrapper component

through which all clients of the graph subsystem must interact in order to use the sub-
system. This wrapper (like component win Figure 5-92b) would not only manage the
other components in the graph subsystem but would also encapsulate several imple-
mentation-level objects previously exposed to the user in the factored implementation.

Recall that in the factored implementation of the graph subsystem, both Gnode and
Gedge were managed by Graph, meaning that Graph alone was authorized to create

17 If animplementation class provides functions that alter static variables within the class or . c file,
this principle may not hold.
section 5.10 Escalating Encapsulation 315

and destroy Gnodeand Gedge objects. In that implementation, both Gnode and Gedge
were not encapsulated details of the subsystem; instances of these types, comprising
the graph's implementation, were readily accessible through the interface of class
Graph itself. To prevent clients from usurping the manager class's authority, much of
the interface to both Gnode and Gedge was declared pri vate, and Graph alone was
granted fri end status. Solely to avoid the breach of encapsulation that would result
from long-distance friendship, we were compelled to place Graph, Gnode, and Gedge
within a single component.

Escalating the level at which encapsulation occurs can remove the

need to grant private access to cooperating components within a
subsystem.

Always trying to force privileged communication to go on within a single component

could make components ridiculously large and would defeat the advantages of a hier-
archical design. If we stop worrying about the encapsulation aspect for a minute and
make all of the functionality in Gnode and Gedge public, we can move each of these
three classes to separate components. Because Gnode and Gedge use each other in
name only, they automatically become testable independent of each other. For exam-
ple, it is now easy and convenient to test directly the full functionality of the new
gnode component shown in Figure 5-93.

In the factored solution, only Graph had private access to Gnode and both classes were
defined in the same component. That approach eliminated the potential for improper
direct use of Gnode by clients, but it precluded direct testing of Gnode as welL

With this new approach, instead of being forced to test the low-level functionality of
Gnode (e.g., adding and removing Gedge pointers) indirectly through the interface of
Gra ph, it is now possible for test engineers to verify this now-pUblic behavior directly.
However, ordinary clients will now also have direct access to this low-level functionality.
316 Levelization ChapterS

II gnade.h
#ifndef INCLUDED_GNODE
#define INCLUDED_GNODE

#ifndef INCLUDED_NODE
#include "node.h"
flendi f

#ifndef INCLUDED_GEDGEPTRBAG
#include "gedgeptrbag.h"
#endif

class Gnode : public Node {

GedgePtrBag d_edges;
Gnode(const Gnode&); II not implemented
Gnade& aperatar=(const Gnode&); II not implemented

public:
Gnode(const char *name);
. . . Gnode() ;
void add(Gedge *edgePtr);
vaid remave(Gedge *edgePtr);
canst GedgePtrBag& edges() canst;
};
#endif

Figure 5-93: New Individual Component gnode Defining Class Gnode

Originally, Graph was granted private access to both Gnode and Gedge to preserve
encapsulation. The encapsulation was at risk only because clients of Grap h were
granted direct access to the Gnode and Gedge objects, which themselves were largely
implementation details of Graph. If we stop exposing Gnode and Gedge in the inter-
face of Graph, we can avoid this problem entirely.

Private header tiles are not a substitute for proper encapsulation

because they inhibit side-by-side reuse.

Failing to publish header files is not the solution-that's cheating. Not granting cli-
ents access to one or more header files will make the use of certain types opaque,
but these types are still programmatically accessible in name and therefore not
section 5.10 Escalating Encapsulation 317

encapsulated details. For example, an opaque pointer obtained from one part of the
system could be unexpectedly reintroduced by clients into another part of the system
in a way that renders the system internally inconsistent.

As Figure 5-94 illustrates, class N manages a collection of objects of type Wand E.

Each of these two subobjects makes use of an S object in its interface. The object S
itself is an implementation detail, so clients are denied access to its header file in an
effort to encapsulate its use.

Figure 5-94: Ineffective Encapsulation by Concealing Header Files

Notice how easy it is for a client to extract an opaque S pointer from an instance of
class Wand use it to influence an instance of class E directly:

void myFuncCE *e, canst W& w)

{
e - >9 C*w . f C) ) ;
}

Compare this approach with a design that properly hides its implementation details
behind an encapsulating interface (i.e., a design where rhere is no exposure of the
implementation types in the logical interface of the wrapper componen~ for that sub-
system). Even with access to all header files, there is still no programmatic way to
318 Levelization Chapter 5

access the low-level implementation objects hiding behind the truly encapsulating
interface of the wrapper.

The advantages of proper encapsulation are many. A clear example is reuse. Trying to
encapsulate an implementation type by withholding a header file effectively prevents
public reuse of that implementation component. If encapsulation is done properly, cli-
ents can have side-by-side access to both low-level types and the subsystems that use
them internally, with no fear that private details of the subsystem will be exposed.

Understandability and maintainability are other advantages of using proper encapsu-

lation. Distinguishing what is and what is not a "private" header file is difficult at best.
For these reasons, providing a single header file per component, which clearly and
fully defines its (sole) interface, is strongly recommended. It is worth noting that
withholding header files may be appropriate when the objective is not encapsulation
but insulation (see Sections 6.5 and 7.4).

DEFINITION: In hierarchical systems, encapsulating a type (defined

at file scope within a header file) means hiding its use, not hiding the
type itself.

Let us now return to our graph example. Successfully levelizing this new graph archi-
tecture will not be achieved by hiding the low-level implementation types of our sub-
system from test engineers and/or clients. It makes no difference what others do with
their own instances of these types. Rather, successful levelization of this architecture
will be achieved by ensuring that there is no programmatic way to access any instance
of any implementation type that is part of an instance of our subsystem.

To implement encapsulation at the subsystem level, we will need to introduce a wrap"

per component. Figure 5-95 gives a detailed sketch of the new architecture for the
graph subsystem. The old Graph class has been renamed Graph Imp, but otherwise bas
been left essentially unaffected. Both Gnode and GraphImp continue to make use of
the factored implementations and specializations in ptrbag (shown as a single com-
ponent in this figure). The new graph (wrapper) component now defines five classes
to be used by clients of the subsystem.
section 5.10 Escalating Encapsulation 319

Level 4:

Level 3:

Level 2:

Levell:

node ptrbag edge

Figure 5-95: Escalating Encapsulation Using a Wrapper Component

A wrapper component can be used to encapsulate the use of

implementation types within a subsystem while allowing other
types to pass through its interface.

The Node and Edge classes, containing only network-independent data, are also pro-
grammatically accessible from the interface of the new graph compone~~. However,
from the perspective of users of the graph subsystem, the types Gnode, Gedge, and
Graphlmp and all types defined in ptrbag are now implementation details that are
fully encapsulated by the new wrapper comp.onent.
320 Levelization Chapter 5

To appreciate this solution, consider that a client who has access to 9nod e . h still can-
not affect any Gnode that has been created through the graph component's interface.
Of course, the user is still free to create and manipulate his or her independent Gnode
instances (i.e., for testing purposes).

Figure 5-96 shows the header file of the wrapper component for the new graph sub-
system. The four additional support classes (Nodeld, Edgeld, Nodelter, and
Edge I te r) establish the encapsulation, and either supply or require private access to
Grap h. All of these classes must therefore reside in the same component as Grap h in
order to avoid long-distance friendships.

Because this wrapper is provided only for encapsulation purposes, it is an extremely

thin wrapper. All of the functions merely forward requests to the appropriate lower-
level implementation components. To avoid the additional function call overhead, all
of the wrapper functions are defined inline, leaving the 9 rap h . c file empty.

II graph.h
#ifndef INCLUDED_GRAPH
#define INCLUDED_GRAPH

#ifndef INCLUDED_GRAPHIMP
#include "graphimp.h"
#endif

#ifndef INCLUDED_GNODE
#include "gnode.h"
#endif

#ifndef INCLUDED_GEDGE
#include "gedge.h"
#endif

class Edgeld; II forward declaration

class Graph; II forward declaration
class NodeIter; II forward declaration
class Edgelter; II forward declaration

class Nodeld {
Gnode *d_node_p;
friend Edgeld:
friend Graph:
friend Nodelter:
friend Edgelter:
section 5.10 Escalating Encapsulation 321

private:
NodeId(Gnode *node) : d_node_p(node) {}
Gnode *gnode() const { return d_node_p; }
public:
NodeId() : d_node_p(O) {}
Nodeld(const Nodeld& nid) : d_node_p(nid.d_node_p) {}
~NodeldC) {}
Nodeld& operator=(const Nodeld& nid) { d_node_p = nid.d_node_p; return *this; }
operator Node *() const { return d_node_p; }
Node *operator-)() const { return *this; }
};

class EdgeId {
Gedge *d_edge_p;
friend Graph;
friend Edgelter;

private:
EdgeldCGedge *edge) : d_edge_p(edge) {}
Gedge *gedge() const { return d_edge_p;

public:
Edgeld() d_edge_p(O) {}
EdgeId(const Edgeld& eid) : d_edge_p(eid.d_edge_p) {}
""'EdgeldC) {}
EdgeId& operator=(const Edgeld& eid) { d_edge_p = eid.d_edge_p; return *this; }
Nodeld from() canst { return NodeId(d_edge_p-)from()); }
NodeId toe) const { return NodeldCd_edge_p-)toC»; }
operator Edge *() const { return d_edge_p; }
Edge *operator-)C) const { return *this; }
};

class Graph {
Graphlmp d_imp;
friend NodeIter;
friend Edgelter;

private:
GraphCconst Gra.ph&); II not implemented
Graph& operator=Cconst Graph&); II not implemented

public:
Graph() {}
~Graph () {}
NodeId addNodeCconst char *nodeName)
{
return NodeIdCd_imp.addNode(nodeName»;
}
Nodeld findNode(const char *nodeName)
{
return NodeIdCd_imp.findNodeCnodeName»);
}
322 Levelization Chapters

void removeNode(const Nodeld& nid)

{
d_imp.removeNode(nid.gnode(»);
}
Edgeld addEdge(const Nodeld& from, const Nodeld& to, double weight)
{
return Edgeld(d_imp.addEdge(from.gnode(), to.gnode(). weight));
}
Edgeld findEdge(const Nodeld& from. const Nodeld& to)
{
return EdgeldCd_imp.findEdge(from.gnode()p to.gnode()));
}
void removeEdgeCconst Edgeld& eid)
{
d_imp.removeEdgeCeid.gedgeC));
}
};

class Nodelter {
GnodePtrBagIter d_iter;

private:
Nodelter(const Nodelter&); II not implemented
Nodelter& operatar=(const Nodelter&); II not implemented

public:
NodelterCconst Graph& graph) : d_iterCgraph.d_imp.nodes(» {}
voi d operator++C) { ++d_ iter; }
operator const void *() canst { return d_iter; }
NodeId operator()() const { return NodeIdCd_iter(»; }
};

class Edgelter {
GedgePtrBaglter d_iter;

private
Edgelter(const Edgelter&); II not implemented
EdgeIter& operator=(const Edgelter&); II not implemented

public:
EdgeIterCconst Graph& graph) : d_iter(graph.d_imp.edges(» {}
EdgelterCconst Nodeld& nid) : d_iter(nid.gnode()-)edges(» {}
void operator++() { ++d_iter; }
operator const void *() const { return d_iter; }
Edgeld operator()C) const { return EdgeldCd_iter(»; }
};

1Fendif

Figure 5-96: Encapsulating Wrapper Component for Graph Subsystem

Section 5.10 Escalating Encapsulation 323

Notice that, in this interface, there is no direct access to any Gnode or Gedge. Adding
or looking up a node returns a surrogate object of type Node I d, which holds a pointer
to a Gnod e, but under no circumstances will a Nod e I d ever let the client have access to
more than just the Node portion of the Gnode it holds.

Similarly, Gedge is no longer exposed. Pointers to Gedge are now replaced by

instances of type Edge I d. When dealing with a Gra ph, you can use an Edge I d just as
you would have used a Gedge pointer. When communicating Edge information you
can use an Edgeld as ifit were an Edge pointer-nothing more.

Modifying the old test driver to accommodate the new wrapper interface requires only
a few minor changes. In particular, CGnode *) types are replaced by Nodeld types
and a few unnecessary 1fi ncl ude directives are eliminated. The output is, of course,
identical. The modified test driver is shown in Figure 5-97.

II graph.t.e
/linclude "graph.hl!
#include <iostream.h>

ostream& operator«(ostream& 0, eonst Graph& graph);

ma i n ( )
{
Graph g;

{
Nodeld nl = g.addNode("Mindy");
Nodeld n2 = g.addNode("Susan");
NodeId n3 = g.addNode("Riek");

g.addEdge(n2, nl, 4):

g.addEdge(n1, n3, 5):
g.addEdge(n3, n2, 1):

g.addNode("Franklin");
g.addNode("Cathy"):
}

g.addEdge(g.findNode("Susan"), g.findNode("Franklin"), 6);

g.addEdge(g.findNode("Rick"), g.findNodeC"Franklin"), 2):
g.addEdge(g.findNode("Rick"), g.findNodeC"Cathy"), 3);

cout « g:
}

Figure 5-97: Driver lliustrating Usage of New graph Wrapper Component

324 Levelization Chapter 5

Use of the wrapper intetface is in some respects simpler than a factored implementation
because most, if not all, of the available functionality is presented in a single, mono ..
lithic header file. For example, to iterate over the edges in a graph or node, we do not
need to look further than the header for graph itself:

int sumOfEdgeWeights(const Nodeld& nid)

(
int sum = 0;
for CEd gel t e r i t Cni d ); it; ++ it) {
sum += itC)-)weight();
}
}

Wrapping has the disadvantage of making the interface less flexible and communication
across it slower. A wrapped subsystem is also likely to be more costly to develop ini-
tially. However, wrapping may be the only truly effective way to achieve both level-
ization and encapsulation for 'subsystems involving many highly interdependent
components.

We have come a long way from the simple two-component example of Figure 5-10 in
Section 5.1.3, but the seven components in Figure 5-95 lay a strong hierarchical foun-
dation for producing a complex yet easy-to-use and highly reliable subsystem. The
topic of wrappers is continued in Section 6.4.3, where we discuss how to insulate our
clients from compile-time dependency on the implementation types below our wrapper
components.

To summarize this section: trying to encapsulate the implementation of a subsystem

on a per-component basis can impede low-level communication and/or warp an other-
wise viable design. Rather than restricting the functionality that is accessible to clients
within individual classes, we can instead restrict the subset of classes exposed to cli-
ents in the interface of the overall subsystem. Using a wrapper component, we can
elevate the level of encapsulation to the highest level of a subsystem. In so doing, we
can eliminate the need for low-level friendships, and thereby eliminate the need for
merging intimately coupled classes into a single, oversized component.

5.11 Summary

By considering the physical implications of our logical design and proactively engi-
neering our system as a levelizable collection of components, we create a hierarchy of
section 5.11 Summary 325

modular abstractions that can be understood, tested, and reused independently of the
rest of our design.

Techniques for achieving levelization include the following:

• Escalation Moving mutually dependent functionality higher in the

physical hierarchy.

• Demotion Moving common functionality lower in the physical

hierarchy.

• Opaque Pointers Having an object use another in name only.

• Dumb Data U sing data that indicates a dependency on a peer object,

but only in the context of a separate, higher-level object.

• Redundancy Deliberately avoiding reuse by repeating small amounts

of code or data to avoid coupling.

• Callbacks Using client-supplied functions that enable lower-level sub-

systems to petform specific tasks in a more global context.

• Manager Class Establishing a class that owns and coordinates lower-

level objects.

• Factoring Moving independently testable subbehavior out of the

implementation of complex components involved in
excessive physical coupling.

• Escalating Moving the point at which implementation details

Encapsulation are hidden from clients to a higher level in the physical
hierarchy.

Using these techniques to create levelizable designs tends to reduce the large, some-
times even overwhelming, logical design space, and helps to guide developers in the
direction of more mainstream, maintainable architectures. Fortunately there is a ser-
endipitous synergy between good logical design and good physical design. Given
time, these two design goals will come to reinforce one another.
 Insulation

Avoiding unnecessary compile-time dependencies is another important part of good

physical design. Excessive compile-time coupling can profoundly impede our ability
to maintain a system. Programmatically inaccessible implementation details that
reside in the physical interface of a component cannot, in general, be modified with-
out forcing all clients to recompile. For even moderately large projects, the cost of
recompiling the entire system will inhibit any modification of the physical interface of
low-level components, limiting our ability to make even local changes to the encapsu-
lated details of their implementations.

In this chapter we present a physical process referred to in this book as insulation,

which is analogous to the logical process commonly referred to as encapsulation.
Insulation is the process of avoiding or removing unnecessary compile-time coupling.

First we establish the need for addressing insulation as part of our overall architectural
design, providing both theoretical and experimental justification. Next, we identify
many specific C++ constructs that can cause compile-time coupling without attempt-
, ing to alleviate it. In Section 6.3, we discuss several techniques for insulating individ-
ual details of the implementation exposed via the following mechanisms:

• private base classes,

• embedded member data,
• private member functions,
• protected member functions,
• enumerations,
328 Insulation Chapter 6

• compiler-generated functions,
• include directives,
• private member data, and
• default arguments.

In Section 6.4, we discuss wholesale techniques used for insulating all details of the
implementation:

• protocol classes,
• fully insulating concrete classes, and
• insulating wrapper components.

Insulating very large subsystems presents a unique problem for developers. In Section
6.5, we explore implementing an ANSI C--compliant procedural interface for a very
large C++ system.

Finally, in Section 6.6, we explore the conditions under which insulation is indicated.
The basic runtime costs associated with insulation will be presented, along with specific
conditions under which insulation is not appropriate. We demonstrate the process of
applying insulation, and measure the runtime costs associated with various degrees of
insulation.

6.1 From Encapsulation to Insulation

Insulation is a physical design issue: its logical analog is commonly referred to as

encapsulation. In Section 2.2 we discussed encapSUlation in terms of classes. ~ Sec-
tion 3.6, we discussed encapsulation in terms of components. Then in Section 5.10,
we discussed encapsulation in terms of classes defined at file scope in the header files
of a hierarchical subsystem. The important aspects in each case are that:

1. Some detail is part of some entity.

2. The detail is not programmatically accessible through the interface

defined for that entity.

Consider the header file for the stack component shown in Figure 6-1. The logical
interface of this St a c k class fully encapsulates its implementation. Programmatically,
Section 6.1 From Encapsulation to Insulation 329

there is no way to distinguish this implementation from the linked-list implementation

with the identical interface shown in Figure 6-2.

II stack.h
#ifndef INCLUDED_STACK
#define INCLUDED_STACK

class Stack {
int *d_stack_p;
int d_size;
int d_length;

public:
Stack() ;
Stack(const Stack &stack);
-Stack();
Stack& operator=(const Stack &stack);
void push(int value);
i nt pop ( ) ;
int tope) canst;
int isEmpty() const;
};

#endif

Figure 6-1: Fully Encapsulated Array-Based Stack Implementation

II stack.h
#ifndef INCLUDED_STACK
#define INCLUDED_STACK

class StackLink;

class Stack {
StackLink *d_stack_p;

public:
StackC);
Stack(const Stack &stack);
""'Stack();
5tack& aperator=(const Stack &stack);
void push(int value);
int pope);
int tope) canst;
int isEmpty() canst;
};

{fend; f

Figure 6-2: Fully Encapsulated Linked-List-Based Stack Implementation

330 Insulation Chapter 6

Even though both St a c k classes fully encapsulate their implementations, any experi-
enced C++ programmer looking at these header files can immediately determine the
general implementation strategy of these components. Each of these stack compo-
nent headers illustrates the difficulty in concealing proprietary implementations even
with encapsulating interfaces. Inline functions can exacerbate the problem by expos-
ing clients to algorithmic details as well.

But the desire to keep component implementations proprietary is not the dominant
problem for large projects. A client has a right to expect that the logical interface of a
component will not change, and ideally changes made to the logical implementation
of a component should not affect clients. In reality, however, the C++ compiler
depends on all information in a header file, including private data. If a human being
can determine the implementation strategy of a component by inspecting its header,
then it is likely that clients of the component would be forced to recompile if the
implementation strategy of that component changes.

Forcing clients to recompile even when only the implementation of a component

changes is not a desirable physical property of a component. The more components
that depend on that component, the more undesirable such compile-time coupling can
become. Failing to "insulate" clients from changes to our logical implementation can
have a dramatic impact on the cost of developing large projects.

Imagine a system with N components in which each component is compile-time

dependent on all the rest. That is, compiling a component means including and pars-
ing the definitions from the header files of all N components. The compile-time cost
of making a change to any single header file in such a system is staggering. Instead of
being proportional to the size of the component itself, the cost of compiling any single
translation unit depends on the size of the entire system! As the size of the entire sys-
tem increases, the cost of compiling anyone component grows at a rate that is dispro-
portionately high. As more headers are read into each translation unit, the compiler's
data structures are taxed more and more heavily. That is, doubling the number of lines
included in a translation unit more than doubles the time it takes to parse it (as demon-
strated in Section 6.1.1).

Even for relatively small systems (say, 50,000 lines total), this type of coupling is burden-
some at best; for medium and large systems, it is intolerable. For example, a . c file that
should take only seconds to compile now takes minutes, and the total compile-time cost
of a single uninsulated change is now measured not in CPU seconds but in CPU hours!
section 6.1 From Encapsulation to Insulation 331

The system illustrated in Figure 6-3 consists of a base class Sha pe, a number of specific
shapes derived from Shap e, and a number of clients that depend only on the base class
shape. This system has no cyclic physical dependencies and is therefore levelizable.

II shape.h
#ifndef INCLUDED_SHAPE
#define INCLUDED_SHAPE

Shape {
int d_x; II could change to short
int d--y; II could change to short
public:
ShapeCint x, int y);
virtual void draw() canst;
int xOrigin() canst;
I I ...
};

#endif

II circle.h II client3.c
#ifndef INCLUDED CIRCLE #include "client3.h"
#define INCLUDED_CIRCLE #include "shape.h"

#ifndef INCLUDED_SHAPE I I ...

#include "shape.h"
#endif void Client3: :draw() canst
{
class Circle: public Shape { II draw each shape
int d_radius; Shape *p;
while (p = nextShape()) {
public: p-)draw();
CircleCint x, int y, int r); }
void draw() canst; }
I I ...
}; I I ...

1Iendif

Figure 6-3: Illustration of a Compile-Time Coupled System

332 Insulation Chapter 6

Originally the author of class Shape decided to use integers to represent the coordinates
of the origin. Later the author realized that the integer range afforded by ash 0 r tin t
was sufficient and that the size of Shape instances could be reduced significantly. The
fundamental type of a private data member used to store the coordinates is clearly an
implementation detail of the Shap e class. The interface would not change, and it would
continue to accept and return normal integers in the valid range (see Section 9.2). In
fact, this detail is entirely encapsulated by the intetface of Sha pee Yet there is a problem.

Suppose that the author of Shap e changes the private coordinate data type from i nt to
short i nt. Which of the components in Figure 6-3 would be forced to recompile?
Unfortunately, the correct answer is "all of them." Both Ci rcl e and Rectangl e
inherit from Shape and depend intimately on the internal physical layout of Shape.
When any of Shape's data members change, the internal layout of Ci rcl e and
Rectangl e will also have to change accordingly.

Clients of Shape are no better off. For one thing, the position of the virtual table
pointer in the physical layout of the Shape object will almost certainly be affected by
the change from i nt to s h 0 r tin t. Unless the dependent code is recompiled, it sim-
ply will not work. More generally, whenever a header file is modified, all clients that
include that header file must be recompiled. Therefore, whenever any part of the
implementation resides in the header file of a component, the component fails to
"insulate" clients from that part of its logical implementation.

DEFINITION: A contained implementation detail (type, data, or

function) that can be altered, added, or removed without forcing
clients to recompile is said to be insulated.

The term encapsulation conjures up an image of a clear bubble of perhaps infinitesi-

mal thickness that surrounds the implementation of a class and protects it only from
programmatic access. The term insulation connotes instead an opaque barrier of finite
thickness that eliminates any possibility of direct interaction with the implementation
of a component.

When bugs occur between internal releases of the various levels of a large system,
insulating components (Le., components that insulate clients from their implementa-
tions) are much more easily patched than non-insulating components. As long as the
Section 6.1.1 The Cost of Compile-Time Coupling 333

interface is not altered, the modified implementation can be dropped in place without
having to recompile other components or worrying about headers becoming out of
date. (We revisit this important topic in Section 7.6.2.)

One final testament to the value of insulation is that it can enable us to replace dynam-
ically loaded libraries transparently. Dynamically loaded libraries are not linked into a
single executable but, rather, are linked on demand into a running program. Suppose
that you are the vendor of some C++-based application library. If you supply a fully
insulated library implementation, then you can provide performance enhancements
and bug-fixes without disturbing your clients at all. Sending them an update does not
force them to recompile or even relink. All they do is reconfigure their environment to
point to the new dynamically loaded library, and off they go.

In the following subsection we take a quantitative look at the cost of compile-time cou-
pling. After that, we look at specific ways in which implementation details in C++ can
become non-insulating, and then discuss transformations that can improve the degree of
insulation.

6.1.1 The Cost of Compile-Time Coupling

To illustrate the severity of the problem, I devised a simple experiment. 1 I mechani-

cally generated a varying number of simple header files, each 100 lines long. All
headers were then included in an otherwise empty . c file. An outline of the generated
files is shown in Figure 6-4.

II file.c II headerO.h II headerl.h II . . .

#include "headerO.h" class Class 0 0 { class Class 1 0 {
1Iinclude "headerl.h" II . . . II . . .
lFinclude "header2.h" }; };
#include "header3.h" class Class 0 1 { class Class 1 1 {
#include "header4.h" II II . . .
#include "header5.h" }; }
II , .. II II

Figure 6-4: Experiment to Measure Compile-Time Cost

I then measured the CPU time needed to compile the . c file. The experiment was
repeated using headers 1,000 lines long instead of 100 lines. Figure 6-5 provides the

1 This
subsection provides experimental data to corroborate the claims in the main section and may
be omitted without loss of continuity.
334 Insulation Chapter 6

results of running this simple experiment using the CFRONT 3.0 compiler running on a
SUN SPARC 20 Workstation with 32 megabytes of memory.

The first column represents the relative size of the system where N represents the
number of components of equal size. The next two columns represent the measured
compile-time cost for headers on the order of 100 lines and 1,000 lines, respectively.

CPU seconds to parse headers

System Size: N
(number of headers) 100-line headers 1,000-line headers

1 0.1 0.4
2 0.1 1.0
4 0.2 3.4
8 0.4 11.0
16 0.8 32.2
32 2.4 137.7
64 8.2 497.5
128 26.5 more than a day
256 98.1
512 397.6
1024 more than a day

Figure 6-5: Empirical Cost of Compile-Time Coupling

If the total number of included lines is around 3,000 (30 small components or 3 large
ones), doubling the number of included lines roughly triples the compile-time cost.
For projects of this scale, the cost of recompiling a single. c file using CFRONT 3.0 is
roughly proportional to N 1.6 and gets progressively worse for larger systems. A trans-
lation unit that might otherwise take only a few seconds to compile might now take
several minutes.

As if this were not bad enough, because each component is compile-time dependent
on every other component, an uninsulated change to anyone component implies that
all others must recompile as well. The cost of a single uninsulated change in a large
compile-time coupled system is not proportional to N 2 but more like N 3 !
section 6.2 c++ Constructs and Compile-Time Coupling 335

If, when compiling any single translation unit, the amount of included header file
information causes the compiler to exceed available physical memory, virtual mem- .
ory swapping will completely overwhelm the cost of compilation, as was the case for
the last entry in Column 2 and the last four entries in Column 3 of Figure 6-5. That is,
for a given compiler and system configuration, there can be fairly hard limits to the
absolute size of any given translation unit. For this particular configuration, 60,000
lines was practical; 100,000 lines was not.

6.2 C++ Constructs and Compile-Time Coupling

Sometimes the logical and physical decompositions of components are naturally con-
sistent with each other. Consider a non-inline member function of a class. Its logical
interface (the declaration) re~ides in the physical interface (the . h file), and its logical
implementation (the function body) resides in the physical implementation (the . c
file). In this case, the declaration merely describes the interface without exposing any
more information than is necessary or desirable.

C++ does not require that all details regarding the logical implementation exist in the
. c file. C++ allows this tight compile-time coupling for performance reasons. For a
small, light-weight component implementing a stack or a list, avoiding compile-time
coupling by completely insulating its implementation could have too great an impact
on performance to be practical. Such light-weight components typically reach a stable
state quickly and then are seldom if ever modified.

In the case of components that provide higher-level functionality such as a parser or

simulator, the amount of useful work done per interface function called is often quite
large. In these situations, the runtime overhead of insulating the implementation is
usually neither measurable nor relevant.

It is easy in C++ to inadvertently introduce implementation details into the physical

interface of a component. Whenever we place any part of the implementation of a
component in its header file, we fail to insulate clients from that part of our imple-
mentation. The logical implementation is made part of the physical interface through
the use of the following constructs:

• inheritance,
• layering,
• inline functions,
336 Insulation Chapter 6

• private members,
• protected members,
• compiler-generated functions,
• include directives,
• default arguments, and
• enumerations.

The implications of each of these constructs with respect to compile-time coupling

are explored individually in the following subsections. Our purpose now is only to
expose the specific nature of the problem, but not to provide a solution just yet. Insu-
lation techniques that systematically address all of these cases begin in Section 6.3.

6.2.1 Inheritance (IsA) and Compile-Time Coupling

Whenever one class derives from another, even privately, there can be no way to insu-
late clients from that fact. Even though private inheritance is considered an encapsu-
lated implementation detail of the derived class, the physical layout of the derived
object forces every client that includes the definition of the derived class to have
already seen the definition of the base class. It is therefore appropriate for the header
file of a derived class to include explicitly the header files containing its base classes.
Whenever a base class header is modified (even if just to add a comment), UNIX util-
ities such as rna ke will feel obliged to recompile any client of a derived class before
linking that client into any new executable.

Figure 6-6 illustrates that if any change is made to the physical interface of B, then not
only 0 but also all clients of 0 (i.e., C1, C2, and C3) will be forced to recompile.
section 6.2.2 Layering (HasAIHoldsA) and Compile-Time Coupling 337

private inheritance

Figure 6-6: Inheritance Cannot Be Insulated from Clients

6.2.2 Layering (HasAIHoldsA) and Compile-Time Coupling

When a class embeds an instance of another user-defined type in its definition

(RasA), the physical layout of the class becomes intimately dependent on the layout
of that type. As a result, it will not be possible for a client to include the class defini-
tion of an object without having already seen the definitions of each of the layered
subobjects embedded in that object. It is therefore appropriate for the header file of a
composite object to include explicitly the header files containing the definitions of
every layered object that is physically embedded within that class.

In contrast, when a class merely holds the address of an object (HoldsA), the class is
not necessarily dependent on the physical layout of the held object. If so, it is appro-
priate for the header containing the class not to include the header for the held object
but instead merely to declare its type.

Figure 6-7 illustrates a situation where class Stooges uses (in its implementation
only) classes Moe, La r r y, and Cur 1y. Unlike classes La r r y and Cur 1y, a Moe is embed-
ded in every Stooges object and therefore is not insulated from clients of Stooges.
Any modification to the header file of Moe will necessitate the recompilation of all cli-
ents of Stooges.
338 Insulation Chapter 6

II stooges.h
#ifndef INCLUDED_STOOGES
#define INCLUDED_STOOGES

#ifndef INCLUDED_MOE
#include "moe.h"
#endif

class Larry;
class Curly;

class Stooges {
Moe d_moe:
Larry *d_larry;
Curly& d_curly;

public:
Stooges();
II
};

#endif

Figure 6-7: Embedded, Layered Objects Are Not Insulated from Clients

Every St a ages object also holds a pointer to an instance of a La r ry and a reference to

an instance of a Cur 1y. It is not necessary for a client of class Stoo 9 e s to know any-
thing about the physical layout of either a La r r y or Cur 1y in order to construct an
instance of class St 0 age s. It is therefore possible to modify the header file of either
La r r y or Cur 1y and not have to recompile any of the clients of class Stoo 9 e s. The
physical layout and functionality of both La r r y and Cur 1y are insulated details of
Stooges.
section 6.2.3 Inline Functions and Compile-Time Coupling 339

6.2.3 Inline Functions and Compile-Time Coupling

A function declared i n 1 i ne must be defined in the header file if it is to be substituted

inline outside the current component. That requirement forces the body of the in line
function to be placed in the physical interface of the component. The body of an inline
function is encapsulated in that it is not programmatically accessible except by calling
it via its own logical interface. Yet this part of the object's logical implementation is
not insulated from clients, which has the following ramifications:

1. Any programmer that can use the component can look at the inline imple-
mentation.

2. Changing the implementation of an inline function forces all clients of

the component defining the inline function to recompile.

3. Changing a function to or from an inline function also forces all clients of

the component defining that function to recompile.

4. An object returned by value from an inline function is used in size (see

Section 5.4) in the header file and is therefore never insulated from cli-
ents (although an object returned by value from a non-inline function
might be). The same applies to an object used in size in the body of an
inline function. Therefore, when a user-defined object is passed into,2 used
in, or returned from an inline function by value, it is appropriate to include
explicitly the header defining the used object in the header file defining the
inline f u n c t i o n . -

Figure 6-8 illustrates ways that inlining can uninsulate otherwise insulated implemen-
tation details of class Fred. For example, Fred holds pointers to objects of type
Wi 1rna,. Betty, Ba rney, and MrSl ate, and therefore Fred's object layout does not
depend on the object layout of any of these types. Because member function
getWi 1rna returns an object of type Wi 1rna by value and is declared i nl i ne, it is neces-
sary for all clients of class Fred to have already seen the definition of class Wi 1rna.
Since member function get Bet ty is not declared i n 1 i ne, clients of Fred that do not
need to call getBetty (and otherwise do not depend on type Betty in size) need not

2 Passing a user-defined type into a function by value is almost never done (see Section 9.1.11),
340 Insulation Chapter, 6

include the header file for class Betty. In other words, clients that do not use tyd
Betty are not forced to depend on Betty at compile time.

II fred.h
#ifndef INCLUDED FRED
#define INCLUDED_FRED

#ifndef INCLUDED_WILMA
#include "wilma.h"
#endif

#ifndef INCLUDED_MRSLATE
/finclude "mrslate.h"
41endif

class Barney;
class Betty;

class Fred {
Wilma *d_wilma_p;
Barney *d_barney_p;
Betty *d_betty_p;
MrSlate *d_mrSlate_p;

public:
Fred();
Wilma getWilma() canst { return *d_wilma_p; }
Betty getBetty() canst; II non-inline function
const Barney& getBarneyC) const { return *d_barney_p; }
double getSalary() { return d_mrSlate_p-)askForRaise(); }
};

#endif -,

Figure 6-8: Ways that Inlining Functions Reduce Insulation

Section 6.2.4 Private Members and Compile-Time Coupling 341

An instance of class Ba rney is returned from member function getBa rney by refer-
ence, so unless a client depends on class Bar n ey in size, there is no need for that client
to include the class definition for Ba rney. Again, the client is not forced to depend on
what it does not need.

Finally, the member function getSal ary makes substantive use of the encapsulated
MrS 1 ate object in its implementation. Because get Sal a r y is declared i n 1 i ne, all cli-
ents of Fred are required to have seen the definition of class MrSl ate, whether or not
they call get Sal a r y. Of course, should any of the implementations of these inline
functions change, all clients of Fred would have to recompile.

6.2.4 Private Members and Compile-Time Coupling

Each private data member of a class-although encapsulated-is not insulated from

clients of that class. We have already seen several examples where modifying the
implementation will require changing private data members, which in tum will
require clients to recompile. For example, changing the encapsulated implementation
of a St a c k class from linked-list based to array based will force all clients of St a c k to
recompile. As we have also already seen, even a trivial code-tuning change, such as
changing an i n t to ash 0 r tin t, is enough to trigger the recompilation of all clients.

We are often reminded that private member functions are encapsulated implementation
details of a class, but they are not insulated implementation details-even when they
are not declared i n1 i n e. Altering so much as the signature of a private member func-
tion of a class is enough to force all clients of the component defining that class to
recompile.

Figure 6-9 illustrates the problem with private members. The d_l ength member is a
detail that was added presumably because it was felt that keeping track of the length
was more efficient than calculating it on demand. If this assumption turns out to be
false, removing d_l ength will cause all clients of this component to recompile. Simi-
larly, the copy function was implemented to factor the copy operation for use in both
the copy constructor and assignment operator. If we now decided to change the signature
of this private helper function from copy(const String&) to copy(const char *)
to enable its use in implementing the default constructor as well, all clients would
again be forced to recompile.
342 Insulation Chapter 6

II str.h
#ifndef INCLUDED_STR
#define INCLUDED_STR

class String {
char *d_string_p;
int d_length;
void copy(const String& string);

public:
String(const char *str);
StringCconst String& string);
-String(const char *str);
String& operator=(const String& string);
II
};

#endif

Figure 6-9: Private Members Are Not Insulated

6.2.5 Protected Members and Compile-Time Coupling

Whe~ considering protected members, base-class authors must now address two dis-
tinct audiences: derived-class authors and general users. Protected functions are in the
interface specifically for derived classes, but are intended to be treated as implementa-
tion details by general users. Note that protected member data is rarely appropriate,
especially in widely used interfaces for which insulation is a design goal.

On the surface, the protected interface provides a convenient place for prospective
derived-class authors to look to determine what will be required of them. However,
just as with private members, the protected interface is declared in the class definition
and is therefore not an insulated implementation detail as far as general users are con-
cerned. Modifying the protected interface of a base class in any way will force the
recompilation of (1) all clients of the base class, (2) all derived classes, and (3) all clients
of the derived classes.

6.2.6 Compiler-Generated Member Functions and Compile-Time Coupling

, Certain basic member functions are generated automatically by the compiler, if

needed, unless they are explicitly declared in a class. 3 In particular, unless a copy

3 See meyers, Item 45, p. 172.

Section 6.2.6 Compiler-Generated Member Functions & Compile-Time Coupling 343

constructor is specified, the compiler will generate one with member-wise copy
semantics. That is, a copy constructor will be generated that copies each member object
and each base-class object according to its own individual initialization semantics.4

In a similar way, an implicit assignment operator also is generated if needed, copying

each member object and each base class part according to its own assignment seman-
tics. A destructor will also be generated if needed, to invoke the destructors of layered
and base-class objects.

In many cases, compiler-generated constructors, assignment operators, and destruc-

tors do exactly what is required. Unfortunately, if the author of a class determines a
need to diverge from the compiler-generated definition, it will be necessary to intro-
duce the appropriate member declaration into the class definition. Any such introduc-
tion of a declaration 'cannot be considered insulated, and any clients of the class will
be forced to recompile.

class ComplexSymbol public Complex {

String d_name;

public:
II CREATORS
ComplexSymbol(const String& name, double ret double im = 0.0);
II Default copy ctor and dtor are fine.
II MANIPULATORS
II Default assignment operator is fine.
II
II ACCESSORS
II
}:

Figure 6-10: Relying on Compiler-Generated Functions

As shown in Figure 6-10, class Camp 1exSymbo 1 implements copy construction,

assignment, and destruction by default. If we decided to eliminate the implementation
dependency of our CamplexSymbal on String and use a char * instead, it would be
necessary to introduce a declaration for the copy constructor, assignment operator,
and the destructor. In this example, the change in private data alone would force our
clients to recompile; however, even if we solved that problem (and we can), introducing

4 See ellis, Section 12.8, p. 295.

344 Insulation Chapter 6

new declarations into the header file of our component is a change that cannot be
insulated from clients.

6.2.7 Include Directives and Compile-Time Coupling

In the experiment at the beginning of this chapter (Section 6.1.1) that demonstrated
the high cost of compile-time coupling, we did not even consider the possibility that
each header might directly include every other header. 5 Instead we assumed that each
. c file explicitly included every header in the system because it needed to do so. In
practice, this scenario does not happen.

What is much more likely to occur is that each header file will include one or more
header files that, in tum, include one or more other header files, until eventually virtu-
ally every header file in the system has been included. This is where redundant
include guards (Section 2.5) help to reduce the cost of compiling by eliminating the
quadratic behavior we observed in the time spent by the C++ preprocessor.

Consider the example in Figure 6-11. A Ban k class uses a Ban k Car d .class and a variety
of currency classes in its interface. The Ban k class does not inherit from any other
class. Let us assume that Ban k does not have any inline functions that make substantive
use of class Ban kCa rd or any of the currency classes. Let us further assume that class
Ban k does not embed instances ot any user-defined class (RasA) in its own definition.

II bank.h
#ifndef INCLUDED_BANK
#define INCLUDED_BANK

#ifndef INCLUDED_BANKCARD
#include "bankcard.h"
#endif

#ifndef INCLUDED_GERMANMARKS
#include "germanmarks.h"
#endif

#ifndef INCLUDED_JAPENESEYEN
#include "japeneseyen.h"
#endif

5 Insome environments, you might encounter a limitation on the number of open source files per-
mitted at anyone time.
;ection 6.2.7 Include Directives and Compile-Time Coupling 345

#ifndef INCLUDED_UNITEDSTATESDOLLARS
1foinclude "unitedstatesdollars.h"
fIend i f

#ifndef INCLUDED_ENGLISHPOUNDS
lfi nc1 ude" eng 1ish po unds . hII

/fendif

I I ..,
I I .,.
II

/fifndef INCLUDED LAKOSIANFOOBARS

Iii nc 1ude" 1a k0 s ian f 0 0 bar s . h"
#endif

class Bank {
I I ...
Bank(const Bank&); II We don't want to copy
Bank& operator=(const Bank&); II or assign banks.

public:
II CREATORS
Bank() ;
,...,Bank();

II MANIPULATORS
GermanMarks getMarks(BankCard *cashMachineCard, double amount);
JapeneseYen getYen(BankCard *cashMachineCard, double amount);
UnitedStateDollars getDollars(BankCard *cashMachineCard. double amount);
EnglishPounds getPounds(BankCard *cashMachineCard, double amount);
II
I I .. .
I I .. .
LakosianFooBars getFooBars(BankCard *cashMachineCard, double amount);
};

#endif

Figure 6-11: Class Using Many Types in Its Interface

Now consider a client of an instance of this Ban k in the United States. This person is
typically interested in going to the bank with his or her bank card and withdrawing
some amount of money in United States dollars. A simple example of a Person's
withdraw member function is shown in Figure 6-12.
346 Insulation Chapter 6

II person.c
ih nc 1ude" per son . h I!

#include "bank.hl!

II ...

void Person::withdrawCdouble amount)

{

Figure 6-12: Simplified Implementation of Person's Withdraw Function

Picture the fictitious island republic of Lakos; its national unit of currency, the
FooBar, is notoriously unstable and subject to change without notice. Today this
country has again announced its intention to make an uninsulated change to its imple-
mentation of FooBar. The world financial community is demanding to know who will
be forced to recompile.

Not only will all actual clients of La k 0 S ian F00 Bar s have to recompile, but so will all
other clients of Ban k. That is, if you banked at this bank, whether or not you ever cared
or had even heard about La k 0 s ian F0 0 Bar s, any change at all to 1 a k 0 s ian f 00 bar. h
will cause software configuration management tools (such as make) to recompile you
automatically.

To add insult to injury, there is no real need for you to be compile-time dependent on
that currency! None of your code depends on that currency at compile time. So why
did ban k' s author decide to include all these header files in ban k . h instead of ban k . c?
The answer you might receive is "for the convenience of our clients."

The author of the bank component believes that just in case you might need some
class definition, we'll include it for you. This approach has the relatively small advan-
tage that as long as you include ban k . h, you will never need to include the header for
Un; tedStatesDoll ars or your BankCard. However, this approach also has the rela-
tively large disadvantage that you will forever be at the mercy of a potentially large
number of header files that you neither control nor otherwise care about.

6.2.8 Default Arguments and Compile-Time Coupling

Often a single algorithm will depend on several parameters-some with reasonable

default values. Placing these default values in the header file defining the interface of
Section 6.2.9 Enumerations and Compile-Time Coupling 347

the function can be more self-documenting simply because they place more informa-
tion in the header file:

class Circle {
II ...
public:
Circle(double x = 0, double y = 0, double radius - I);
I I ...
};

Unfortunately, such default values become compiled in along with the interface and
any modification of those values will force clients to recompile.

6.2.9 Enumerations and Compile-Time Coupling

Enumerations, CPP macros, typedefs, and (by default) non-member canst data do not
have external linkage (see Sections 2.3.3 and 2.3.4). As such, these constructs must
appear in the header file of a component if they are to be used byotber components (or if
they appear in the body of any inline functions intended for use outside the component).

Figure 6-13 illustrates the common practice in small projects of grouping all system-
wide definitions into a single component. As more components are added to the sys-
tem, these components will typically include this common definitions file. Whenever
the need for a new definition or return status is encountered, it is added to the
sysdefs. h file. The more components that are added, the more opportunities there
are to add to the common definitions. Whenever a common definition is added to
sysdefs . h, almost all components in the system are forced to recompile.

Eventually the system reaches the point where making an addition to the global defi-
nitions is simply too expensive. Instead of placing a useful definition in this file, they
are kept local or private. Instead of adding new specific return status values to the enu-
meration, preexisting codes (such as UNSPECIFIED_ERROR) are used over and over,
even though they are vague or even inappropriate.

II sysdefs.h
#ifndef INCLUDED_SYSDEFS
. #define INCLUDED_SYSDEFS
#ifndef INCLUDED_MATH
#include <math.h> II bad idea: should be insulated
#define INCLUDED_MATH
#endif
348 Insulation Chapter 6

const double PI_BY_4 = M_PI/4; II bad idea: should be class member

const double PI_BY_B = M_PI/8; II bad idea: should be class member

struct SysDefs {
typedef int (*Pfdi)(double);
typedef double (*Pfid)(int);

enum ReturnStatus {
SUCCESS = 0,
WARNING,
IOERROR,
FILE_NOT_FOUND,
I I ...
OUT_OF_RANGE,
I I ...
OUT_OF_MEMORY,
II .. .
I I .. .
INVALID_GEOMETRY,
II
I I .. .
I I .. .
UNSPECIFIED_ERROR
};
};

#endif

Figure 6-13: Component Containing Common Definitions

The problem here is that enumerations and typedefs are not implementation details
but rather are plainly part of the public interface of a component. The interface of this
component is not a well-organiz.ed, cohesive presentation of a single abstraction.
Instead it is an eclectic hodgepodge of details. This all too common use of enumera-
tions does not scale well as project size increases.

The compile-time coupling in this system arises because this interface is driven not
from the lower levels of the physical hierarchy but from the yet-to-be-implemented
higher levels. This upward dependency imposes an implicit compile-time coupling
among all clients, even though these clients are in unrelated parts of the system. This
example is an instance of a more general problem, involving the sharing of ownership
for a component.

In the following section we discuss specific techniques for addressing this and other
problems related to insulation.
section 6.3 Partial Insulation Techniques 349

6.3 Partial Insulation Techniques

Not every component should attempt to insulate its clients from every implementation
detail. But, all other things being equal, it is better to insulate a client from an imple-
mentation detail than not to do so-even if only to reduce the clutter in the physical
interface.

Fortunately insulation need not be an all-or-nothing proposition. Insulating one detail

of the implementation can be desirable-even when other implementation details
remain uninsulated. The more insulated the implementation of a component is, the
less likely that changes to that implementation will force clients of the component to
recompile. r'

Sometimes insulating an implementation detail is as easy as not insulating it. As with

low-hanging fruit, we can often reap significant benefits while expending negligible
effort. Other times insulation can require considerable and deliberate work. The
amount of effort worth expending on insulating any given implementation detail
comes down to the degree to which changes in that detail are likely to affect clients.

The following subsections provide a collection of specific techniques for selectively

reducing the number of implementation details exposed in the physical interface of a
component.

6.3.1 Removing Private Inheritance

Unlike public (and protected) inheritance, private inheritance is an implementation

detail. One of the "advantages" of private inheritance over layering is the notational con-
venience of selectively exposing some but not all of the functions in the private base
class to clients of the derived class via access-declarations6 or using-declarations. 7

Figure 6-14 illustrates how a class can privately inherit from another class and then
selectively publish all members with a given name in its own interface using an access
declaration.

-
6 ellis,Section 11.3, p. 244.
7 strollstrup94, Section 17.5.2, p. 419.
350 Insulation Chapter 6

// base.h /1 myclass.h
#ifndef INCLUDED_BASE #ifndef INCLUDEO_MYCLASS
#define INCLUDED_BASE
C'
#define INCLUDED_MYCLASS

class Base { #ifndef INCLUDED_BASE

// ... #include "base.h"
public: #endif
Base();
,...,Ba s e ( ) ; class MyClass : private Base {
void fl(int); public:
void f2(double); My C1 ass () {}
int fIe) canst; Base::fl; // access declaratio~
double f2() canst; };
};
#endif
#endif

(a) Private Base Class Header File (b) Derived Class Header File

Figure 6-14: Private Inheritance and Access Declaration

The usefulness of the access declaration is dubious for a couple of reasons. It exposes
a set of functions in the public interface, yet in order for a client to know "Yhat those
functions are, the client must look at the header of the privately derived (implementa-
tion) class in order to know the appropriate arguments and return values. Another
problem is that this class fails to insulate its client from its private base class. The cli-
ent is exposed to changes in private (unpublished) functions that may not even be used
in the implementation of the derived class.

One reason for using private inheritance instead of layering is to take advantage of
the virtual table(s) of the base class. By overriding the behavior of the virtual func-
tions declared in a private base class, we may be able to "customize" or "program"
other behaviors that depend on the overridden behavior at the base-class level. It also
is possible to invent a dummy class for derivation purposes and then proceed with lay-
ering using that dummy class. If insulation is not an issue, then private inheritance
may be appropriate. If, however, this class is to become part of a more generally pub-
lic interface, then a transformation from inheritance to layering is in order.

Figure 6-15 illustrates how the same logical interface as the one in Figure 6-14b can
be achieved without exposing clients to the details of the implementation class.
Instead of privately deriving from class Base, the new implementation holds an out-
wardly opaque pointer to class Bas e. Whenever an instance of My C1 ass is created, the
Section 6.3.1 Removing Private Inheritance 351

appropriate constructor, declared non-i n 1 i ne, dynamically allocates a new instance

of Base and assigns its address to the d_base_p member of MyCl ass. When this
instance of My C1 ass is destroyed, the non- i n1 i n e destructor will delete this instance.
The assignment operator will also need to manage this base object pointer appropriately.

II myclass.h II myclass.c
#ifndef INCLUDED_MYCLASS #include "myclass.hll
#define INCLUDED_MYCLASS #include "base.h"

class Base; MyClass::MyClassC) : d_base_p(new Base) {}

class MyClass { MyClass::MyClass(const MyClass& c)

Base *d_base_p; : d_base_pCnew BaseC*c.d_base_p)) {}

public: My C1ass: : ""My C1ass () { del e t e d_b as e_p ; }

MyClass();
MyClass(const MyClass& c); MyClass& MyClass: :operator=Cconst MyClass& c)
,..,MyClass(); {
if Cthis != &c) {
MyClass& operator=(const MyClass& c); delete d_base_p;
void fI(int i); d_base_p = new MyClassC*c.d_base_p);
}
int fIC) const; return *this;
}; }

#endif v0 i d f 1 ( i nt i) { d_b as e_p - >f 1 Ci ); }

int fIe) canst { return d_base_p->fl(); }

(a) Insulating Header File (b) Insulated Implementation File

Figure 6-15: Using Layering Instead of Private Inheritance

Instead of using access declarations to publish members of a private base class selec-
tively, new member functions of MyCl ass are defined (out-of-line) to forward their
calls to corresponding functions defined in class Ba s e. Note that all member functions
of My C1 ass that depend on Bas e in size must be declared non- i n1i ne if clients are to
be insulated from the definition of Bas e.

In this way, class My C1 ass now insulates its clients from all organizational changes to
class Base. Had class Base been abstract, then d_base_p would point to a dummy
concrete class derived from Base, perhaps implemented entirely in file myclass.c.
Note that all of this insulation is not without its cost (e.g., extra function calls and
dynamic allocation), as discussed in detail in Section 6.6.1.
352 Insulation Chapter 6

6.3.2 Removing Embedded Data Members

Even if performance requirements prevent us from fully insulating a class, we can still
insulate clients from an individual implementation class by converting all embedded
instances of that implementation class to pointers (or references) to that class and then
managing those pointers explicitly in the constructors, destructors, and assignment
operators of the class.

Figure 6-16 shows how we can selectively insulate clients from implementation
classes by converting a RasA relationship (Figure 6-16a) to a HoldsA relationship
(Figure 6-16b). In doing so we must redeclare all inline functions that formerly oper-
ated on My C1 ass data members of type You r C1 ass to be non-inline. The downside of
HoldsA is the increased effort required to manage the layered instance; and also the
additional performance costs associated with indirection, dynamic allocation, and
non-inline functions. Notice how we can continue to access performance-critical
member data (such as d_count) via inline functions.
section 6.3.3 Removing Private Member Functions 353

II myclass.h II myclass.h
#ifndef INCLUDED_MYCLASS #ifndef INCLUDED_MYCLASS
#define INCLUDED_MYCLASS #define INCLUDED_MYCLASS

#ifndef INCLUDED_YOURCLASS class YourClass:

#include "yourclass.h"
#endif class MyClass {
int d_count:
class MyClass { YourClass *d-yours_p;
int d_count;
YourClass d-yours; public:
I I ...
public: int yourValue() canst;
/ I ...
int yourValue() const int count() const
{ {
return d-yours.value(); return d_count;
} }
};
int count() const
{ #endif
return d_count;
}
}:

4fendif
(a) Before Insulating You r C1 ass (b) After Insulating You r C1 ass
from Clients of MyC 1 ass from Clients of My C1 ass

Figure 6-16: Converting HasA to HoldsA to Improve Insulation

6.3.3 Removing Private Member Functions

Private member functions, although encapsulated logical implementation details of a

class, are part of the physical interface of a component. Non-inline private member
functions have external linkage; this enables functions and classes declared to be
friends of this class and defined in other translation units to call them. However, as
discussed in Section 3.6, befriending any function or class defined outside a compo-
nent invites undisciplined clients to take advantage of private details of our class.
Avoiding long-distance friendship implies that only functions and classes defined
within a single component may have access to private members. Fortunately C++
(and even C) supports a more restrictive, component-wide form of access control.
354 Insulation Chapter 6

Instead of making the function a private member of the class, make it a static free
function declared at file scope in the . c file of the component. 8

Sometimes functions are made private members not because they need private access
but because the private section of the header file is a good place to store these factored
helper functions. That is, some private helper functions can do all of their work using
only the public interface of the class. In these cases, the transformation from private
member to static free functions is easy and quickly accomplished in two steps.

The first step is to convert each private member function to a private static member by
adding an appropriate writable pointer or read-only reference parameter to the func-
tion. Consider class My C1 ass, as defined in Figure 6-17 a. Class My C1 ass contains two
private member functions, fand g. Member f is a non-canst (manipulator) function
and member 9 is a canst (accessor) function. The manipulator f potentially alters the
object, so, in keeping with our policy (see Section 9.1.1), we will pass the instance by
non-canst pointer along with the o~her arguments to the function. The accessor 9 is
innocuous and we will pass the instance by con s t reference along with g' s other argu-
ments, as shown in Figure 6-17b.

II myclass.h II myclassoh
#ifndef INCLUDED_MYCLASS #ifndef LNCLUDED_MYCLASS
#define INCLUOED_MYCLASS #define INCLUDED_MYCLASS
class MyClass { class MyClass {
I I ... II 000

private: private:
void f( ... ); s tat i c v0 i d f ( My C1 ass *my C1 ass, .. 0 ) ;

int g( ... ) canst; static int g(can"st MyClass& myClass, .0.);

public: public:
II II 00'

}; };

#endif 1tendif

(a) Original Class with (b) Modified Class with Only

Private Member Functions Private Static Member Functions

Figure 6-17: Making Private Member Functions Static Members

8 We will be able to achieve this same effect more elegantly using unnamed namespaces, as dis-
cussed in strollstrup94, Section 17.5.3, pp. 419-420, once this relatively new language feature
becomes more widely available.
section 6.3.3 Removing Private Member Functions 355

The second step is to remove these function declarations entirely from the header file,
remove the member notation from function definitions in the. c file (shown in Figure
6-18a), and finally precede each of these definitions by the keyword s tat i c, as shown
in Figure 6-18b. Note that this second step should not require any changes to the
implementations of the other member functions defined in the . c file.

II myclass.c
#include "myclass.h"
v0 i d My C1ass: : f ( My C1ass *my C1ass, ... ) { 1* ... * I }
i nt My C1ass : : 9 ( con s t My C1ass & my C1ass, ...) { I * ... * I }
I I ...

(a) Original Class with Private Static Member Functions

II myclass.c
#include "myclass.h"
static void f(MyClass *myClass, ... ) { 1* ... *1 }
static int g(const MyClass& myClass, ... ) { 1* ... *1 }
II

(b) Modified Class with Static Free Functions

Figure 6-18: Converting Static Member Functions into Free Functions

Unfortunately, private member functions often operate directly on other private imple-
mentation details, which can make these functions more difficult to extricate. Con-
sider the 1 i st component defined in Figure 6-19. Class List contains three private
member functions-copy, c1 ean, and end-that are used repeatedly to help imple-
ment the public functionality of class Lis t.

The copy function is already a static member, but it needs access to the auxiliary
("slave") class Lin k. Both c 1 e an () and end ( ) depend on access to the private data
member d_h e a d_p that identifies the head of the list, and there are no public functions.
that can be used to obtain access to it. Making these three functions non-members of
Lis t will strip them of their privileged access to the implementations of both Lis t
and Lin k. Although these functions will no longer have access to the private details of
either class, the callers of these functions are members with full access, and they are
at liberty to offer up this information.
356 Insulation Chapter 6

II list.h
#ifndef INCLUDED_LIST
#define INCLUDED_LIST
class List;
class Listlter;
class astream;
class Link {
int d_data;
Link *d_next_p;
friend List;
friend Listlter;
Link(const Link& link); II not implemented
Link& operator=(const Link& link); II not implemented
II CREATORS
Link(int data, Link *next = 0);
}:
class List {
Link *d_head_p;
friend ListIter;
private:
static Link *copy(const Link *link, Link *end = 0);
II allocate and return new copy of given list of links
void clean();
II destroy and deallocate entire list of links
Link *& end();
II return a reference to the end of the list
public:
II CREATORS
List();
List(const List& list);
,..,List();
II MANIPULATORS
List& operator=(const List& list):
void append(int i);
Y0id append(const List& list);
","" \/0 i d pre pen d ( i nt i):
void prepend(canst List& list):
};
ostream& operator«(ostream& 0, canst List& list);
class Listlter {
/ I ...
};
#endif

Figure 6-19a: 1 ; st. h File for L; st Class with Private Member Functions
Section 6.3.3 Removing Private Member Functions 357

II list.c
#include "list.h"
#include <iostream.h)
II **********
II class Link
II **********

II CREATORS
Link::Link(int data, Link *next) : d_data(data), d_next_p(next) {}

II **********
II class List
II **********
II PRIVATE MEMBERS
Link *List::copy(const Link *link, Link *end)
{
Link* linkPtr = end:
for (Link **addrLinkPtr ~ &linkPtr; link; link = link->d_next_p)
*addrLinkPtr = new Link(link-)d_data, *addrLinkPtr);
addrLinkPtr - &(*addrLinkPtr)->d_next_p;
}
return linkPtr:
}

void List::clean()
{
while (d_head_p) {
Link *tmp ~ d_head_p;
d_head_p = d_head_p->d_next_p;
delete tmp:
}
}

Link *& List: :end()

{
Link **addrLinkPtr = &d_head_p;
while (*addrLinkPtr) {
addrLinkPtr = &(*addrLinkPtr)->d_next_p;
}
return *addrLinkPtr;
}

II CREATORS
Lis t : : Lis t () : d_h e ad_p ( 0 ) {}
List::List(const List& list) d_head_pCcopy(list.d_head_p» {}
List: :-List() { clean(); }
358 Insulation Chapter 6

II MANIPULATORS
List& List::operator=(const List& list)
{
if (this != &list) {
clean();
d_head_p = capyC1ist.d_head_p);
}
return *this;
}

void List: :append(int i) { endC) = new Link(;); }

void List::append(canst List& 1) {endC) = copYC1.d_head_p): }

void List::prepend(int ;) { d_head_p = new LinkC;, d_head_p); }

II FREE FUNCTION
astream& operator«(astream& a, canst List& list)
{
o « f[';
for (Listlter it(list); it; ++it) {
o « ' , « it();
}
return 0 « " ]";
}
II **************
II class Listlter
II **************
I I ...

Figure 6-19b: 1 i st. c File for List Class with Private Member Functions

As shown in Figure 6-20, we can modify both the c1 ean and end helper member
functions so that they, like copy, are declared stat; c and take as arguments the pri-
vate infonnation to which they need access. Clients of these two functions must noW
provide a little more infonnation when they make the call, but these functions will no
longer have to rely on private access to the Lis t class to do their jobs. The only prob-
lem that remains is that these functions still depend on access to the private function-
ality of the encapsulated Link class in order to accomplish their tasks.
section 6.3.3 Removing Private Member Functions 359

II list.h

I I ...

class List {
I I ...
private:
static void clean(Link *link);
static Link *& end(Link **addrLinkPtr);
I I ...
};
II list.c
II
II

void List::clean(Link *link)

{
while (link) {
Link *tmp = link;
link = link->d_next_p;
delete tmp;
}
}

Link *& List: :end(Link **addrLinkPtr)

{
while (*addrLinkPtr) {
addrLinkPtr = &(*addrLinkPtr)-)d_next_p;
}
return *addrLinkPtr;
}

II

Figure 6-20: Passing Private Information into Static Free Functions

One solution is to make the needed functionality in the Lin k class publicly accessible.
Since the use of Lin k is an encapsulated implementation detail of Lis t, there is little
hann that can come from allowing clients (or test engineers) to play with separate
instances of the Lin k class. However, a better solution from an insulation point of
view is to move the trivial definition of the Lin k class to the . c file and make it
entirely public. Not only does this solution increase the insulation of the 1 i 5 t compo-
nent's implementation, but it also eliminates a lot of unnecessary clutter in its header
file. The improved version of 1i st is shown in Figures 6-21a and 6-21b.
360 Insulation Chapter 6

II list.h
#ifndef INCLUDED_LIST
#define INCLUDED_LIST

class Link:
class List;
class Listlter:
class ostream;

class List {
Link *d_head_p;
friend ListIter;

public:
II CREATORS
List();
List(const List& list);
''''ListC);

II MANIPULATORS
List& operator=(const List& list);
vo; d append Ci nt i);
void append(const List& list);
void prepend(int i);
void prepend(const List& list);
}:

ostream& operator«Costream& 0, canst List& list);

class ListIter {
I I ...
};

lFendif

Figure 6-21a: 1 i st. h File for 1 i s t Component with Static Free Functions
section 6.3.3 Removing Private Member Functions 361

II list.c
#include "list.h"
#include <iostream.h>
II **********
II class Link
II **********
struct Link {
int d_data;
Link *d_next_p;

Link(const Link& link); II not implemented

Link& operator=(const Link& link); II not implemented
II CREATORS
Link(int data t Link *next -0)
};

II **********
II class List
II **********
II STATIC FREE FUNCTIONS
static Link *copy(const Link *linkt Link *end - 0)
{
Link* linkPtr = end;
for (Link **addrLinkPtr = &linkPtr; link; link = link->d_next_p) {
*addrLinkPtr = new Link(link->d_data, *addrLinkPtr);
addrLinkPtr = &(*addrLinkPtr)->d_next_p;
}
return linkPtr;
}

static void clean(Link *link)

{
while (link) {
Link *tmp = link;
link = link-)d_next_p;
delete tmp;
}
}

static Link *& end(Link **addrLinkPtr)

{
while (*addrLinkPtr) {
addrLinkPtr = &(*addrLinkPtr)-)d_next_p;
}
return *addrLinkPtr;
}
362 Insulation Chapter 6

II CREATORS
Lis t: : Lis t C) : d_h e ad_p ( 0 ) {}
List::ListCconst List& list) : d_head_pCcopyClist.d_head_p) {}
Lis t : :,..., Lis t () { c 1e an Cd_h e ad_p); }

II MANIPULATORS
List& List::operator=Cconst List& list)
{
if (this != &list) {
cleanCd_head_p);
d_head_p = copyClist.d_head_p);
}
return *this;
}

void List: :appendCint i) { endC&d_head_p) = new Link(i); }

void List: :appendCcanst List& 1) { endC&d_head_p) = capyCl.d_head_p);

void List::prependCint i) { d_head_p = new Link(i, d_head_p); }

II FREE FUNCTION
ostream& operatar«Costream& 0, canst List& list)
{
o « '[';
for CListIter it(list); it; ++it) {
o « ' , « itC);
}
return a « " ]";
}
II **************
II class Listlter
II **************
II

Figure 6-21b: 1 i st. c File for '-i st Component with Static Free ~unctions

Sometimes private member functions can be converted to static free functions that are
independent of the types defined in the current component. If these functions are non-
trivial, it could be advantageous to attempt to verify them directly_ Instead of creating a
single component with inaccessible yet non-trivial static free functions, consider mak-
ing two components-one with public static members used to implement the other.

Figure 6-22 illustrates the result of moving independent static functions at file scope
from the my c 1 ass. c file and making them into publicly accessible static member
section 6.3.4 Removing Protected Members 363

functions in a separate utility component. This technique makes sense when the func-
tions are either reusable or non-trivial, and it is especially useful when the CCD of
these functions alone is very much smaller than it is for the original component.

II myclass.c II myclassimputil.h
#include "myclass.h" #ifndef INCLUDED_MYCLASSIMPUTIL
#include "myclassimputil.h" #define INCLUDED_MYCLASSIMPUTIL

void MyClass::func(int x) struct MyClasslmpUtil {

{ static int g(int y);
i nt z = My C1ass Imp Uti 1 : : 9 ( x) ; static double feint a, int b);
I I ... II
double w = MyClasslmpUtil ::f(ztx); };
I I ...
} #endif

(a) Original Component's. c File (b) New Component's. h File

Figure 6-22: Moving Static Free Functions to Another Component

Although static functions are preferable to private members with respect to compile-
time coupling, performance can become an issue, especially if there is a lot of private
state infonnation that must be passed into and out of the static functions at file scope.
In such cases, other, more general forms of insulation (discussed in Section 6.4) may
be preferable.

6.3.4 Removing Protected Members

What are protected members good for? That is, when is it appropriate to have pro-
tected access to class members? The simplistic answer is that protected members are
appropriate when you wish to distinguish between two distinct audiences: derived-
class authors and general users. The protected interface is every bit as important as the
public interface when it comes to encapsulating private details (see Section 2.2), yet
the protected interface is often given less attention than the public one. Realize that
even though the protected interface of an individual instantiated object is not accessi-
ble by the pUblic, anyone can derive a class that depends on these protected details.

The next question is then, "When would someone want to address two distinct audi-
ences from within a single class?" More often than not, the answer is, "When some-
one is trying to do too much with a single class."
364 Insulation Chapter 6

Supplying support for derived-class authors in the form of protected

member functions of a base class exposes public clients of the base
class to uninsulated implementation details of the derived classes.

Consider the header for the abstract base class Shape shown in Figure 6-23. Presum-
ably each derived-shape object has an origin and an area, and knows how to draw
itself on a given .Screen. The screen object provides all the functionality needed to
draw lines and arcs; however, writing the code to achieve this has been found to be
both tedious and error prone. Knowing this, the author of the Shap e base class has
provided a suite of protected member functions to aid the derived-class author in
implementing his or her own specialized d raw function.

Figure 6-24 illustrates a derived Rectangl e class and the implementation of its draw
function using protected helper functions provided in the base class. The Rectangl e
is defined only by its lower-left and upper-right comers, which implicitly forces the
edges of the Rectangl e to be horizontal and vertical. The derived-class author has
also defined the lower-left comer to coincide with the origin of the shape.
section 6.3.4 Removing Protected Members 365

II shape.h
#ifndef INCLUDED_SHAPE
#define INCLUDED_SHAPE
#ifndef INCLUDED_POINT
#include "point.h"
#endif
class Screen;
class Shape {
public:
II TYPES
enum Status { 10_ERROR ~ -1, SUCCESS - 0 }:

private:
II DATA
Point d_origin;
Status d_drawStatus;

protected:
II DERIVED CLASS SUPPORT
static double distance(const Point& start, const Point& end):
void resetDrawStatus();
Status getDrawStatus() const;
void drawLine(Screen *screen. const Point& start, canst Point& end);
void drawArc(Screen *screen, const Point& center, double radius,
double startAngle, double endAngle);
private;
Shape& operator=(const Shape&); II not implemented
Shape(const Shape&); II not implemented
public:
II CREATORS
Shape(canst Point& origin):
virtual -Shape();

II MANIPULATORS
void setOrigin(const Point& origin);

II ACCESSORS
const Point& origin() const:
virtual double area() const = 0;
virtual Status draw(Screen *screen) - 0;
};

#endif

Figure 6-23: Shape Class with Protected Support for Derived-Class Authors
366 Insulation Chapter 6

II rectangl~.h
#ifndef INCLUDED_RECTANGLE
#define INCLUDED_RECTANGLE

#ifndef INCLUDED_SHAPE
#include "shape.hl!
Ifendif

class Rectangle: public Shape {

Point d_upperRightCorner;

public:
II CREATORS
Rectangle(const Point& lowerLeft, canst Point& upperRight);
RectangleCconst Rectangle& rect);
---Rectangle();

II MANIPULATORS
Rectangle& operator=(const Rectangle& reet);
void setUpperRightCorner(const Point& upperRight);

II ACCESSORS
const Point& upperRightCorner() const;
double area{) const;
Shape::Status draw(Screen *screen);
};
II rectangle,c
#endif #include II rec tangle.h ll

I I ...

Shape::Status Rectangle::draw(Screen *screen)

{
resetDrawStatus();
int xl - origin().x();
int y1 - origin().y();
int x2 - upperRightCorner().x();
int y2 - upperRightCorner().y();
drawLine(screen, Point(x1, y1), Point(x1, y2»;
drawLine(screen, Point(x1, y2), Point(x2, y2»;
drawLine(screen, Point(x2, y2), PointCx2, y1»;
drawLine(screen, Point(x2, y1), Point(x1, y1»;
return getDrawStatus();
}

Figure 6-24: Derived Rectangl e Shape and the Implementation of Its Draw Member
section 6.3.4 Removing Protected Members 367

In order to draw a Rectangl e, we will need to draw four lines. If any error occurs we
will need to return 10_ERROR from the Rectangl e:: draw function. Our first step is to
clear the draw status. We then identify the appropriate coordinates and make the nec-
essary calls to the protected helper functions. If any error occurs along the way, these
helper functions will internally set the draw status to I O_E RRO R. When we are done,
we simply return the draw status.

This is one way of doing business that is convenient for base-class authors and
derived-class authors alike, but takes its toll on general clients by compile-time cou-
pling them to numerous implementation details that they neither need nor want. This
scenario is illustrated by the component/class diagram in Figure 6-25.

Figure 6-25: Component/Class Diagram for Original Shape System

In this case there is little justification for polluting the public interface of class Shap e
with details that only the derived-class authors care about. Suppose that instead of
having each of the derived classes depend on services provided in the base class, each
derived class uses a separate component (if needed) to facilitate drawing. This way, the
unnecessary coupling associated with the protected members would be eliminated.
..
As Figure 6-26 shows, the new system is now factored so that the derived-class
authors use a separate scri be component that the general public does not see.
368 Insulation Chapter 6

In Name Only

Figure 6-26: Component/Class Diagram for New Shape System

The header for the scri be component is shown in Figure 6-27. Since the functionality
provided in this new component is no longer embedded in Shape, we have decided to
uncouple it completely. The drawing functionality no longer depends on Shap e in any
way, and now this facility can readily be reused by objects other than those derived
from Shape that might need to render themselves on a Screen.

II scribe.h
#ifndef INCLUDED_SCRIBE
#define INCLUDED_SCRIBE

class Screen;
class Point;

class Scribe {
int d_hadError;
Section 6.3.4 Removing Protected Members 369

private:
Scribe& operator=(const Scribe&); II not implemented
Scribe(const Scribe&); II not implemented
public:
II STATICS
static double distance(const Point& start, canst Point& end);

II CREATORS
Scribe();
"'"'Scribe();

II MANIPULATORS
vaid drawLine(Screen *screen, canst Point& start, const Point& end);

void drawArc(Screen *screen, canst Point& center, double radius,

double startAngle, double endAngle);
II ACCESSORS
int hadErrar() canst;
};

#endif

Figure 6-27: New Reusable scri be Component to Facilitate Drawing

Derived-class authors will not find it difficult to use the public members of class
Sc r i be instead of the protected members of the base class. Since the 5 C r i be compo-
nent is provided only as a convenience, those who do not find its functionality useful
need neither include its header nor depend on it at link time. The reimplemented d raw
function for Rectangl e is shown in Figure 6-28. The new version of the header for
the Shape base class is given in Figure 6-29.

Occasionally it is not feasible to remove all of the protected members of a class. Such
is the case when the derived class needs access to protected services provided by a
base class in order to override virtual functions.
370 Insulation Chapter 6

II rectangle.c
1finclude "rectangle.h"
#include "scribe.h"

Shape::Status Rectangle::draw(Screen *screeh)

{
Scribe u;
int xl = origin().x();
int yl = origin().y();
int x2 = upperRightCorner().x();
int y2 =upperRightCorner().y():
u.drawLine(screen, Point(xl, yl), Point(xl,y2»;
u.drawLine(screen, Point(xl, y2), Point(x2,y2»;
u.drawLine(screen, Point(x2, y2), Point(x2,yl»;
u.drawLine(screen, Point(x2, yl), Point(xl,yl»;
return u.hadError() ? 10_ERROR: SUCCESS;
}

Figure 6-28: New Implementation of Rectangl e: : Draw

An abstract base class that defines some shared functionality is sometimes referred to
as a partial implementation. This type of factored implementation allows derived-
class authors to share a common implementation, but protected functionality again
places a burden on general users of the base class by exposing them to uninsulated
implementation details.

II shape.h
#ifndef INCLUDED~SHAPE
#define INCLUDED_SHAPE

#ifnde·f INCLUDED_POINT
#include "point.hl!
/fendif

class Screen;

class Shape {
Point d_origin;

private:
Shape& operato·r=(const Shape&); II not implemented
Shape(const Shape&); II not implemented
public:
II TYPES
enum Status { IO_ERROR = -1. SUCCESS = 0 };
section 6.3.4 Removing Protected Members 371

II CREATORS
Shape(const Point& origin);
virtual -ShapeC);

II MANIPULATORS
void setOrigin(const Point& origin);

II ACCESSORS
canst Paint& origin() canst;
virtual double area() canst = 0;
virtual Status draw(Screen *screen) - 0;
};

4rend if

Figure 6-29: Shape Class with Protected Member Functions Removed

For example, Figure 6-30 illustrates a simple base class that is used both to provide a
common interface and to factor the common implementation for cars. All cars have a
location, yet the public cannot alter that location directly. Instead, clients must call the
public member function d r i ve that, in tum, will cause the location of the car to
change in various ways, depending on the implementation of the actual (derived) car.

II car.h
#ifndef INCLUDED_CAR
#define INCLUDED_CAR

class Car (
int d_xLocation;
int d-yLocatian;

private:
Car(const Car&); II not implemented
Car& operatar=(canst Car&); II not implemented
protected:
Car(int x. int y);
int setXLocation(int x):
int setYLocation(int y);
II Only derived classes can set the location of a car directly.
void move(;nt deltaX. int deltaY);
static double distancel(double acceleration, double time):
static double distance2(double acceleration, double velocity);
double howFar(int newXlocation, int newYLocation) const;

public:
II CREATORS
virtual -Car();
372 Insulation Chapter 6

II MANIPULATORS
virtual void drive(/* ... */) = 0:
II Public clients alter the location of the
II car by calling the public function drive.

II ACCESSORS
int xLocation() canst:
int yLocatian() canst:
};

#endif

Figure 6-30: Ca r Base Class Containing Protected Member Functions

Several helper functions have been supplied in the protected interface of this base
class in order to aid derived -class authors in implementing the d r i ve function of their
own specific class. For instance, the function move takes relative distances and sets the
new absolute location of the Car. Static functions dis tan eel and dis tan c e 2 are inde-
pendent of instance data and provide support for physical distance calculations. The
how Far accessor function compares the current position with a specified new position
and returns the as-the-crow-flies distance between the two points.

Unlike the Shap e base class, however, Car's interface defines a pure virtual function
d r i ve that, depending on the actual derived type of Car, must in tum set the value of
the Ca r's location using protected functions provided by its partial implementation.

The design of the Car base class couples the interface with at least a portion of the
implementation. Now if a car manufacturer wants to develop an entirely new design
for a car, it is forced to carry around the overhead of the partial implementation
defined in the base class whether or not it is used!

In the case of Ca r, some of the functionality (e.g., the static functions and the howFa r
accessor) could certainly be moved to a separate utility class, as was done for Shape.
But extricating the partial implementation from this base class requires a more com-
prehensive effort.
Section 6.3.4 Removing Protected Members 373

(a) Original Car Hierarchy (b) Insulated Car Hierarchy

Figure 6·31: Extracting a Protocol for Car

Figure 6-31 a illustrates the component/class diagram for the original uninsulated sys-
tem. By factoring the pure interface and partial implementation of Ca r into two sepa-
. rate classes (Car and Carlmp, respectively), we will be able to separate them
physically. By placing the pure interface in a separate component, we provide an insu-
lating interface for public clients of Car, as illustrated in Figure 6-31 b. Note that since
Car I mp derives from Car, further derived classes that choose to share the common
implementation may continue to do so. Fortunately, changes made to the physical
organization of Car I mp cannot affect clients of Car. The extracted protocol for a Car is
shown in Figure 6-32.
374 Insulation Chapter 6

II car.h
#ifndef INCLUDED_CAR
#define INCLUDED CAR

class Car {
public:
II CREATORS
vir t ua 1 ---C a r ( ) ;

II MANIPULATORS
virtual void drive(/* ... */) = 0;
II Public clients alter the location of the
II car by calling the public function drive.
II ACCESSORS
virtual int xLocation() const = 0;
virtual int yLocation() const = 0;
};
II carimp.h
#endif #ifndef INCLUDED_CARIMP
#define INCLUDED CARIMP

class Carlmp : public Car {

int d_xLocation;
i nt d-y L0 cat ion;
I I ...
public:
I I ...
II ACCESSORS
int xLocation() canst;
int yLocation() canst;
};
carimp
#endif

Figure 6-32: Protocol and Partial Implementation for a Car

What we have done in order to insulate the general users from all of the implementa-
tion details is to extract a pure interface (referred to in this book as a protocol).
Extracting a protocol is a very general and powerful technique for simultaneously
achieving both levelization and insulation. Protocol classes and how to extract them
are the subject of Section 6.4.1.
section 6.3.5 Removing Private Member Data 375

6.3.5 Removing Private Member Data

As you may recall, in the previous section we were able to eliminate all of the pro-
tected members from the Shap e base class by introducing a separate facility to support
the implementation of draw functions in derived classes. But the base class Shape still
contained private data.

II myclass.h II myclass.h
#ifndef INCLUDED_MYCLASS #ifndef INCLUDED_MYCLASS
#define INCLUDED_MYCLASS #define INCLUDED_MYCLASS

class MyClass { class MyClass

static int s_count:
I I ... I I ...
public: public:
II II
}; };
II myclass.c II myclass.c
#endif #include "myclass.h" #endif #include "myclass.h"
int MyClass::s~count; static int s_count:
I I ... I I ...

(a) Original Class with (b) Modified Class with

Private Static Member Data Static File-Scope Data

Figure 6-33: Removing Private Static Member Data

Removing private static member data is relatively easy. Figure 6-33a shows a private
static integer data member, s_count, used to track the number of active instances of
My C1 ass. As long as inline member functions (or long -distance friends) do not require
direct access, it is usually possible to move static member data to a static variable
defined at file scope in the component's. c file. 9 Removing non-static member data is
considerably more involved.

As we saw in Section 6.3.4, changing this encapsulated private data would force all pub-
lic clients of base class Shap e to recompile. As was done with Car in the previous sec-

9 Invery rare situations, allowing components to have more than one . c file enables developers of
to
reusable libraries to partition member function definitions based on usage patterns in order reduce
the runtime size of typical client programs. Allowing functions to communicate via static variables
defined in the . c file reduces the flexibility to partition the individual member functions of a class
into separate translation units ( . c files).
376 Insulation Chapter 6

tion, we can factor Shap e into two classes, one containing the pure interface and the
other containing the partial implementation (including the definition of the origin data).

The component/class diagram for the factored Sha pe hierarchy is given in Figure 6-34.
There are two distinct advantages to this architecture:

1. Clients of the Shap e class are insulated from all implementation details of
the actual object derived from Shape.

2. It is possible to derive an entirely new sUbtype of Shap e without incurring

any of the overhead associated with the partial implementation now
defined in Sha pe Imp.

Class Shape no longer embeds an instance of Poi nt, so clients of Shape are no longer
forced to include the definition of Poi nt in order to use a Shape. Derived classes can
continue to share the partial implementation of Shape by deriving from Shapelmp
instead of from Shape. As always, there is absolutely no additional runtime cost asso-
ciated with extending the depth in an inheritance hierarchy. The only additional cost is
that the member functions 0 rig i nand s etO ri gin, which were statically bound, must
now be invoked through the virtual calling mechanism (see Section 6.6.1).

We may decide to try an alternate partial implementation of Shape, MyShapelmp, that

makes use of a pair of s h0 r tin t data members to hold the internal representation of
the origin instead of a Poi nt. The original architecture simply does not support this
degree of reimplementation. Even if the ori gi n and setOri gi n member functions
had been declared virtual, the original architecture would have forced each instance to
carry around an extra data member of type Poi nt.

With the new factored architecture, the choice of implementation is unrestricted. We

can now provide that alternate efficient partial implementation for Sha pe, derived
directly from Shape. Specific concrete shapes derived from Shapelmp, MyShapelmp,
or even directly from Shape itself could coexist in the same running system without
affecting other shapes or clients.
section 6.3.5 Removing Private Member Data 377

Figure 6-34: Component/Class Diagram for Factored Shape Subsystem

A protocol class for an arbitrary shape is given in Figure 6-35. Even though the Shape
class now insulates all implementation details from its public clients, we would still
opt to keep the support for drawing in a separate component for two reasons:

1. As previously mentioned, maintaining the support for drawing as a sepa-

rate screen facility independent of the Shap e hierarchy enables its reuse
in rendering objects other than those derived from Shape (or Shapelmp).
Embedding these support functions within Shapelmp would couple a spe-
378 Insulation Chapter 6

cific partial implementation with more generally useful functionality. It

would not, for example, be possible for My Shap e I mp to take independent
advantage of the support for drawing if that support were defined in the
Shapelmp class.

2. The scri be component provides an optional service and is not an essen-

tial property of the partial implementation. Derived-class authors who
find they have no need for this functionality should not only be insulated
from it but should not even have to link to it during testing.

II shape.h
#ifndef INCLUDED_SHAPE
#define INCLUDED_SHAPE

class Point;
class Screen;
class Shape {
public:
II TYPES
enum Status { lO_ERROR = -1, SUCCESS = 0 };

II CREATORS
virtual ~Shape();

II MANIPULATORS
virtual void setOrigin(const Point& origin) = 0:

II ACCESSORS
virtual canst Point& origin() const = 0:
virtual double area() canst = 0;
virtual Status draw(Screen *screen) = 0;
};

#endif

Figure 6-35: Protocol for a Shape

6.3.6 Removing Compiler-Generated Functions

Changing the definition of any compiler-generated function implies modifying the

class definition to add the corresponding declaration. Any such modification would
force all clients of the class to recompile. While it may be convenient to allow the
compiler to generate a copy constructor, assignment operator, and/or a destructor (if
needed), a truly insulating class must define these members explicitly. Often these
section 6.3.7 Removing Include Directives 379

explicitly defined functions will duplicate their default behavior. In particular,

destructors will often be defined with an empty implementation. Such is the price of
flexibility. (For other reasons to declare these particular functions explicitly, see Sec-
tions 9.3.2 and 9.3.3.)

6.3.7 Removing Include Directives

Unnecessary include directives can cause compile-time coupling where none would
otherwise exist. There are generally three cases where a Hi ncl ude directive should
appear in the header file of a component:

1. IsA: A class in this component derives from a class defined in the

included file.

2. RasA: A class in this component embeds an instance of a class defined in

the included file.

3. Inline: A function declared inline in this component's header file uses a

class defined in the included file in size.

Infrequently, a header file that contains a local linkage construct (such as enum or
typedef in ,class scope) can be another plausible excuse for including one header file
in another. In general, however, there are few other situations in which placing a
Hi n elude directive in a header file is justified.

As we saw earlier in the Bank example (Section 6.2.7), the bank component author's
decision to include each of the foreign currencies was no favor at all to the clients of
class Ba n k. The fact that these currencies appeared (in name) in the interface in no
way implied that Ban k 's clients needed to know their definitions in order to make
good use of Bank. The artificial compile-time dependency of Person on all these for-
eign currencies was solely the result of the nested Hi nc 1ude directives.

The transformation is simple: move all unnecessary include directives from the header
file to the . c file, and replace them with appropriate ("forward") class declarations.
The class declaration tells the client's C++ compiler that the currency represents some
user-defined object type but says nothing about its internal layout. Clients of Ban k are
now insulated from changes made to types they don't use. The easily made insulating
version of the ba n k component is shown in Figure 6-36.
380 Insulation Chapter 6

II bank.h
#ifndef INCLUDED_BANK
#define INCLUDED_BANK

class BankCard; II class declaration instead of #include

class GermanMarks; II class declaration instead of f/include
class JapaneseYen; II class declaration instead of #include
class UnitedStatesDollars; II class declaration instead of lIinclude
class EnglishPounds; II class declaration instead of #include

II
II
I I ...

class LakosianFooBars;

class Bank {
I I ...
Bank(const Bank&); II We don't want to copy
Bank& operator=(const Bank&); II or assign banks.

public:
II CREATORS
Bank();
-Bank();

II MANIPULATORS
GermanMarks getMarks(BankCard *cashMachineCard, double amount);
JapaneseYen getYenCBankCard *cashMachineCard, double amount);
UnitedStateDollars getDollars(BankCard *cashMachineCard, double amount);
EnglishPounds getPoundsCBankCard *cashMachineCard, double amount);
I I .. .
I I .. .
I I .. .
LakosianFooBars getFooBars(BankCard *cashMachineCard, double amount):
};

#endif

Figure 6-36: Insulating Class Using Many Types in Its Interface

In general, wherever it is feasible to remove an inline function or alter a data member

so as to make a 1ft inc 1 ude directive in a header unnecessary, a positive benefit by way
of reduced compile-time coupling has been realized. If this unnecessary Ifi ncl ude
directive is removed, however, clients that previously depended on this header file to
include another will now have to be modified to include that header file directly.
Section 6.3.8 Removing Default Arguments 381

6.3.8 Removing Default Arguments

It is easy enough to remove default arguments from an interface and replace them
with equivalent individual functions: 10

class Circle {
I I ...
public:
Circle(double x = 0, double y = 0, double radius - 1);
I I ...
};

We can change the above interface to the more insulating version as follows:

class Circle {
I I ...
public:
Circle();
Circle(double x) II do we really want this?
Circle(double x, double y);
Circle(double x, double y, double radius);
I I ...
};

Upon reflection we may decide not to provide the identical functionality and to remove
one or more of the options created for us automatically with default arguments.

We can sometimes eliminate the compile-time coupling and yet preserve the factoring
of default arguments by interpreting an invalid optional value (e.g., a null pointer, a
zero size, or a negative index) within the body of the function itself. Recall that in the
interface for the p2p_Router (Figure 4-2) there was a function fi ndPath that took an
"optional" first argument, which was the address at which to store the result:

class p2p_Router {
I I ...
public:
I I ...
int findPath(geom_Polygon *returnValue, canst geom_Point& start,
canst geom_Point& end, int width) canst;
}:

-
10 eUis, Section 8.2.6, p. 142.
382 Insulation Chapter 6

By rearranging the order of arguments, we could have made this argument truly
optional without hard-coding any uninsulating value in the interface:

class p2p_Router {
II ...
public:
II ...
int findPath(const geam_Point& start. canst geom_Point& end,
int width, geom_Polygon *returnValue = 0) canst;
};

Default parameters are discussed further in Section 9.1.10.

6.3.9 Removing Enumerations

Enumerations in the interface by their very nature evoke compile-time coupling. Judi-
cious use of enumerations, typedefs, and all other constructs with internal linkage in
the interface is essential to achieving good insulation.

Consider the three distinct kinds of enumerations shown in Figure 6-37. The first is a
private implementation detail of the class, the second is a publicly accessible constant
value, and the third is a named, enumerated list of return status values.

II whatever.h
#ifndef INCLUDED_WHATEVER
#define INCLUDED_WHATEVER

class WhatEver {
enum { DEFAULT_TABLE_SIZE = 100 }; II 1

public:
enum { DEFAULT_BUFFER_SIZE = 200; }; 112

enum Status { A, B, C, 0, E, F, G, H, I, J }; 113

Status doItC);
};

Ifendif

Figure 6-37: A Class Containing Three Distinct Kinds of Enumeration

The first enumeration in Figure 6-37 is inappropriately placed (unless you need .a
compile-time constant in the header--e.g., to implement a fixed array bound). ThIs
enumeration should either be moved to the . c file at file scope or, if necessary, be
Section 6.3.9 Removing Enumerations 383

made a private static con s t member of the class. Representing this number as a static
class data member gives both inline functions, and functions with friend status
defined outside this translation unit, programmatic access to its value, without expos-
ing a "magic number" in the header file.

The second enumeration should at least be made a private static can s t class member,
and a public static (perhaps inline) accessor member function should be defined to
return this value. As with most insulation techniques (see Section 6.6.1), we pay a price
in runtime performance for the reduced coupling. In this case, an optimizing compiler
can take advantage of known compile-time constants, such as fundamental data
declared canst at file scope, enumerators, and literals. By storing actual values (rather
than addresses) directly in the instruction stream, an extra level of indirection can be
avoided. By definition, however, these compile-time constants cannot be insulated
from clients. Hence, any attempt to change them will inevitably force client recompila-
tion. If this level of performance across this interface is an issue, then this component is
probably at too low a level to be considered a good candidate for insulation.

"""'" , ........................................................................ \),.................... ·······1

I ...•...
l'~i-ill!·I;JI.ioli, .... ~

Granting higher-level clients the authority to modify the interface of

a lower-level shared resource implicitly couples all clients.

The third enumeration is clearly part of the interface. It may be that not all of these
status values are returned by functions in this component, but rather that this compo-
nent has been chosen to hold status values for other components as well. However, to
reduce compile-time coupling, a much preferred approach is to distribute the status
values to the appropriate components and not to attempt to reuse them. Distributing
the enumerated status values greatly reduces coupling by allowing the enumeration to
be independent of higher-levels in the physical hierarchy. Defining return values
locally has the added value of not trying to coerce subtly different meanings into
already existing status values. Each status value's meaning is local to the current
object and exactly suited for its purpose. Reusing status values is but one more case
where the benefit of reuse is more than offset by the coupling that ensues. A possible
alternative to the definitions in Figure 6-37 is illustrated in Figure 6-38.
384 Insulation . Chapter6

II whatever.h
#ifndef INCLUDED_WHATEVER
#define INCLUDED_WHATEVER

class WhatEver (
static canst int s_defaultBufferSize; II 2
public:
static int getOefaultBufferS;ze(); II 2
en urn Stat us { A. B. C }; II 3
Status daltC);
};

inline int getOefaultBufferSize() II 2

{
return d_defaultBufferSize;
}

lIendif

(a) whatever. h Header File

II whatever.c
lIinclude "whatever.h"

enum { DEFAULT_TABLE_SIZE = 100 }; 111

canst int WhatEver::s_defaultBufferS;ze = 200; 112

WhatEver::Status WhatEver::doltC) { 1* ... *1 };

(b) whatever. c Implementation File

Figure 6-38: Alternative Definitions for the Three Enumerations of Figure 6-37

It is possible to get around the compile-time coupling of enumerations in the interface

by instead passing integers or character strings. This practice does indeed remove
compile-time coupling. However, having an enumeration in the interface of a function
especially as a parameter, can be a useful form of coupling that helps to ensure the con-
sistency of the program; it is not this kind of coupling that insulation seeks to eliminate.

Consider a function that returned a "bad" status value as a character string. Clients
would be required to know the exact form of the string. Since this value is insulated,
even determining this string the first time can be challenging for clients. Now, sup"
pose that one of the returned strings happened to change from i 0 Er ra r to 10_ERROR.
There would be no compiler support to help clients track down all places where the
Section 6.4 Total Insulation Techniques 385

comparison value in the calling routines would need to change. Even ignoring the
possibility of change, inevitable spelling errors will surely go undetected.

In general, the goal of, insulation is to shield clients from the compile-time depen-
dency associated with knowing unnecessary, encapsulated implementation details; it
is not to meant to shield clients from the programmatically accessible interface or to
compromise type safety.

6.4 Total Insulation Techniques

In a well-planned, well-architected system, we will know in advance which interfaces

are public and which are not. This knowledge will help us to decide which interfaces
should be insulating and which should not. Designing an interface to be insulating
from the start is always easier and less costly than trying to insulate it after the fact.

In practice, developers may fail to consider all of the ramifications of their design
decisions. Sometimes it will be necessary to insulate a particularly poorly designed
class from the rest of the system, but applying individual insulation techniques would
be tedious and unnecessarily costly.

Fortunately there are wholesale techniques for distancing the implementation of a

class, a component, or even an entire subsystem from its interface without disturbing
its working implementation. The physical motivation behind these techniques can be
found in a few other texts on C++. II Often these techniques are motivated from an
entirely logical perspective. 12 Many of them introduce one or more new components
that serve as insulating interfaces for what now will become the implementation.
Using these techniques, we can sometimes improve the quality of a sloppy interface
so that it reaches the standard it should have met in the first place.

11 meyers, Item 34,- pp. 111-116; murray, Section 3.3, pp. 72-74.
12 gamma, Abstract Factory, Chapter 3, pp. 87-96; Facade, Chapter 4, pp. 185-194.
386 Insulation Chapter 6

6.4.1 The Protocol Class

In the ideal case, a perfectly insulating interface defines absolutely no implementa_

tion; it merely specifies an interface through which clients may access and manipulate
instances of derived concrete classes. 13

DEFINITION: An abstract class is a protocol class if

1. it neither contains nor inherits from classes that contain member
data, non-virtual functions, or private (or protected) members of
any kind,
2. it has a non-inline virtual destructor defined with an empty
implementation, and
3. all member functions other than the destructor including inher-
ited functions, are declared pure virtual and left undefined.

A protocol class is an abstract class that has no user-specified constructors, no data,

and only public members. The component itself does not include any other headers
except for those defining other protocols from which this protocol inherits (see
Appendix A). All member functions (except the destructor) are declared pure virtual.
Many compilers will need at least one non-inline function implementation in order to
know in what translation unit to place the virtual function tables (see Section 9.3.3).
Since the destructor is the only member function that is not declared pure virtual, it is
the only viable candidate for implementing out-of-line in a protocol class.

· · ·.·.:;/ I
·i.············ .................••..•..•............ / ............................ < ....••.

1i,1~• •III\l:t1iij),i -
A protocol class is a nearly perfect insulator.
-

13 Thisrequirement is sometimes relaxed to permit extralinguistic support for runtime type infonna" .
tion (RTfI) as is discussed in Appendix A.
Section 6.4.1 The Protocol Class 387

Figure 6-39 illustrates a protocol for a simple file abstraction. The . c file for this
abstraction is nearly empty and contains only the following three lines:

II file.c
#include "file.h"
File::---File() {} II defined empty and out-of-line

Note that encoding the location as an integer instead of as an enumeration would have
allowed us to add new integer values without requiring existing clients to recompile.
In the same vein, we could then also remove or change these values without being
able to detect the inconsistency at compile time. Removing compile-time coupling at
the expense of compile-time type checking is typically undesirable.

II file.h
#ifndef INCLUDED_FILE
#define INCLUDED_FILE

class File {
public:
II TYPES
enum From { START, CURRENT, END };

II CREATORS
virtual ---File(); II not pure virtual!
II MANIPULATORS
virtual void seekCint distance, From location) = 0;
virtual int read(char *buffer, int numBytes) = 0;
virtual int writeCconst char *buffer, int numBytes) - 0;

II ACCESSORS
virtual int tell (From location) - 0;·
};

#endif

Figure 6-39: Protocol for a File

Instead we have chosen to define the set of valid location values explicitly in the inter-
face. It is therefore appropriate to enumerate them in class Fi 1 e. This enumeration is in
no wayan implementation detail; it is strictly part of the logical interface of class Fi 1e.
That is, adding to or changing this enumeration is like adding to or changing the set of
virtual functions-all derived classes and all clients would be forced to recompile.
388 Insulation Chapter 6

Class Fi 1e is abstract: it defines a complete interface but no implementation. For

example, one cannot construct an object of type Fi 1e on the program stack as an auto-
matic variable. Somewhere, someone must derive a concrete implementation class
from Fi 1 e and instantiate it. Perhaps a manager component (such as the one shown in
Figure 6-40) is used to keep track of files.

II filemgr.h
#ifndef INCLUDED_FILEMGR
#define INCLUDED_FILEMGR

struct FileMgr {
static File *openCconst char *filename);
};

#endif

Figure 6-40: Header for a File Manager Component

One or more of the clients in a system may call upon the Fi 1eMg r in order to create an
instance of Fi 1 e I mp-a concrete implementation class derived from the protocol
class Fi 1 e. Once it is created, a pointer to the implementation object can be passed
around the system as a pointer to an object of type Fi 1e with no compile-time depen-
dencies whatsoever on its implementation.

Figure 6-41 illustrates a system that uses type Fi 1 e, yet is entirely insulated from its
implementation. Class Sub Sy s 1 is the part of the system that is responsible for instan-
tiating new objects of type Fi 1e, and is therefore link-time, but not compile-time,
dependent on class Fi 1 elmp. Both SubSys2 and SubSys3 merely use the Fi 1e proto-
col. These components are neither compile-time nor link-time dependent on Fi 1eMgr
or even on Fi 1 elmp. As such, both components subsys2 and subsys3 can be tested
independently of Fi 1 eMgr. These components can even be tested independently of
Fi 1 e I mp if a suitable stub implementation class is supplied for the Fi 1 e protocol in
the test drivers.
section 6.4.1 The Protocol Class 389

Figure 6-41: System Using a File Protocol

A protocol class can be used to eliminate both compile- and link-time

dependencies.

As we saw with the library subsystem example in Figure 5-32, extracting a protocol
can be used to break cyclic link-time d~pendencies.By physically separating the
Report's interface from its implementation, we allowed StatUti 1 to depend on the
lower-level Report protocol while only the higher-level Reportlmp partial implemen-
tation depended back on Stat Uti 1. What is new and important here is that ~hanges to
the higher-level implementation component---even in its header file~an have abso-
lutely no compile-time effect on any clients on the same or lower level of the protocol.

Sometimes we will encounter an instantiatable base class that declares some of its
functions vi rt ua 1. Often this class contains private data. Sometimes this class will
390 Insulation Chapter 6

contain private or protected functions. Some member functions may be declared

i n 1 i n e. The class may contain static functions and enumerations intended for use by
derived classes; it may contain protected (or even private) virtual functions intended
for precisely that same audience. This class may even derive from or embed instances
of other classes that are not programmatically accessible through the public interface
of this class. In short, there may be a whole lot more going on in this class than a pub-
lic client needs to know about.

Consider an instantiatable base class called E1em fitting the description of the previous
paragraph whose usage is suggested in Figure 6-42. The public interface of E1em is
used widely throughout the system by clients to manipulate objects of type El em (or
derived from E1em). The system architect has thoughtfully isolated the creation of
E1 em objects to a single client, eli en t 1.

Figure 6-42: Using a Non-Insulating E1 em Base Class

section 6.4.1 The Protocol Class 391

Unfortunately the intrinsic lack of insulation in the E1em base class exposes all clients
of class E1 em to the many unnecessary encapsulated implementation details described
above. Clearly the design of the El em base class is far from perfect and, ideally, it
should be reworked. Reworking (like working in the first place) will require signifi-
cant thought and effort. For now, we can insulate the general public from unnecessary
details by extracting a protocol from class E1 em.

As illustrated in Figure 6-43, the idea is to create a protocol class at a lower level and
then to escalate static and constructor functionality to a utility class at a higher level.
The protocol will contain only the information needed to access and manipulate
instances of types derived from El em. The utility will support all static methods,
including insulated support for the creation of concrete instances of types derived
from E1 em.

(a) Single Non-Insulating Component (b) Multiple Insulating Components

Figure 6-43: Extracting a Protocol for Base Class El em

Consider the original header for class El em shown in Figure 6-44.

II elem.h
#ifndef INCLUDEO_ELEM
#define INCLUDED_ELEM
392 Insulation Chapter 6

#ifndef INCLUDED_FDa
lIinclude "foo.hl!
#endif

#ifndef INCLUDED_BAR
ftinclude "bar.hl!
flendif

class Elem {
Faa d_fooPart;
Bar d_barPart;

private:
// ...
protected:
// ...
public:
enum Status { GOOD = O. BAD. UGLY};
Elem();
Elem(const Foo& fooPart);
Elem(const Bar& barPart);
Elem(const Foo& faoPart. const Bar& barPart);
Elem(const Elem& elem);
virtual ----Elem();
Elem& operator=(const Elem& elem);
static double fI() { /* ... */ };
static void f2(double d);
Foo f3() const { /* .,. */ };
void f4(const Foo& foo);
virtual const char *f5() const;
virtual void f6(const char *name);
virtual Status f7();
};

#endif

Figure 6 .. 44: Original Header for a Highly Non-Insulating E1 em Class

We can extract a protocol from class E1em as follows:

1. Copy the existing component e 1em, containing base class E1em, to a neW
name, elemimp, and rename the contained.class to Elemlmp. Any class
that previously inherited directly from E1em should now be changed to
inherit directly from E1 emlmp. This modification will require adjusting
the inheritance portion of the class definition of any derived classes along
with the #i ncl ude directives of each component containing one or more
of those classes. Derived-class constructor initialization lists may require
section 6.4.1 The Protocol Class 393

some adjustment as well. Note that the El em type arguments and return
values of all existing non-constructor members of E1 em I mp should remain
of type E1 em (i.e., should not be changed to type E1 em I mp).

2. Delete all but the public interface of the original E1em class. If enumera-
tions or typedefs specified in class scope are types used in the interface of
one or more non-static, public functions of E1em, they should remain.

3. Remove the constructors and all other static member functions from the
class, but be sure to leave a virtual destructor, declared non-inline and
defined empty.

4. Make all of the remaining member functions in class E1em pure virtual
and remove their definitions.

5. Remove all #i nc1 ude directives from the el em component. Provide "for-
ward" class declarations when a user-defined type is used in the interlace
of a pure virtual function. The new insulating E1 em class should now
appear as in Figure 6-45.

II elem.h
#ifndef INCLUDED ELEM
#define INCLUDED_ELEM

class Faa;

class Elem {
public:
enum Status { GOOD = 0, BAD, UGLY};
virtual ~Elem(); II defined out-of-line and empty
virtual Elem& operator=(const Elem& elem) = 0;
vi rtua 1 Foo f3() const = 0;
virtual void f4(const Foo& foo) = 0;
virtual const char *f5() canst = 0;
virtual void f6(const char *name) = 0;
virtual Status f7() = 0;
};

#endif

Figure 6-45: New Insulating Protocol Component e1em

394 Insulation Chapter 6

6. Modify class E1em I mp to publicly inherit directly from class E1em. The
header for the base class, e 1 em. h, should now be included directly in the
header for the partial implementation, e 1emi mp . h. Each of the pUblic
non-static member functions is now declared vi rtua 1 and should proba-
bly (although not necessarily) be declared non-i nl i nee Special consider-
ation should be given to the implementation of the virtual assignment
operator

virtual Elem& operator=(const Elem& elem)

now inherited from class E1 em as well as the new non-virtual operator

Elemlmp& operator=(const Elemlmp& elemlmp)

defined explicitly for this concrete implementation class.

7. Remove from E1em I mp any redundant interface information such as

enumerations and typedefs that are already specified in the interface of
the new protocol class, E1 em.

The new E1 emlmp class should now appear as in Figure 6-46. The use of
/ * vir t ua 1 * / indicates that the vir t ua 1 keyword is optional. The nOll-
in line static functions defined in the original E1 em class were part of its
interface and could have been left in the base class. However, had we
done so, we would have been faced with the following unpleasant alterna-
tives:

• If we define the functions in the base class E1 em to forward calls to

the derived class E1em Imp, we would violate levelization (see Sec-
tion 4.7).

• If we implement the definition of the actual E1em functions in the

e 1 em; mp component, we would violate the Major Design Rule
requiring components to implement the functionality they export
(see Section 3.2).

• If we implement the functions directly in the e 1 em. c file, we would

physically couple our protocol interface to a specific implementation,
violating the definition of a protocol given earlier in this section.
section 6.4.1 The Protocol Class 395

II elemimp.h
#ifndef INCLUDED_ELEMIMP
#define INCLUDED_ELEMIMP

#ifndef INCLUDED_ELEM
#include "elem.hl!
#endif

#ifndef INCLUDED_Faa
#include "foo.hl!
#endif

#ifndef INCLUDED BAR

#include "bar.h"
ffoendi f

class Elemlmp : public Elem {

Foo d_fooPart;
Bar d_barPart;

private:
I I ...
protected:
I I ...
public:
Elemlmp();
Elemlmp(const Foo& fooPart);
Elemlmp(const Bar& barPart);
ElemImpCconst Foo& fooPart. canst Bar& barPart):
ElemlmpCconst Elemlmp& elemlmp):
1* virtual *1 ~ElemlmpC):
1* virtual *1 Elem& operator=(const Elem& elem);
Elemlmp& operator=(const ElemImp& elemImp);
static double fIC) { 1* ... *1 }
static void f2Cdouble d);
1* virtual *1 Foo f3C) const;
1* virtual *1 void f4(const Foo& foo);
1* virtual *1 const char *f5() const;
1* virtual *1 void f6(const char *name);
1* virtual *1 Status f7();
}:

#endif

Figure 6-46: New Implementation Component e1em; mp

It would be nice if we could retain the original interface; however, none

of the above alternatives is particularly palatable.

8. To preserve levelization and to ensure complete insulation, from E1 emImp

396 Insulation Chapter 6

create yet another component, e1em uti 1, containing the s t r uc tEl emU til.
Be sure to include e1emi mp. h in e1emu til. c. Move all of the static
member functions defined in E1 em to E1 em I mp. Now copy all of the public
static functions formerly defined in E1 em into E1 emUt i 1 and reimplement
them (out of line) to forward all of the client's requests to the correspond-
ing functions now defined in class E1 emlmp.

9. Since E1 emlmp is not abstract (i.e., since it does not contain any pure vir-
tual functions), it will be desirable to provide an insulated mechanism for
clients so they can instantiate instances of type E1 em I mp without actually
including the non-insulating class definition. (A separate component will
be needed to insulate the creation of every object derived from class
E1 em I mp as well.) For each of the constructors defined in E1 em I mp, define
a new static member function in class ElemUti1, named createElem,
taking precisely the same argument signature as the constructor and
returning a pointer to a dynamically allocated, fully constructed instance
of class E1 em I mp as a pointer to a non-c 0 n s tEl em.

The new insulating ElemUtil class should now appear as in Figure 6-47.

II elemutil.h
#ifndef INCLUDED_ELEMUTIL
#define INCLUDED_ELEMUTIL

class Elem;
class Foo;
class Bar:

struct ElemUtil
Elem *createElemC);
Elem *createElem(const Foa& faoPart);
Elem *createElem(const Bar& barPart);
Elem *createElem(canst Foa& faaPart, const Bar& barPart);
Elem *createElem(const Elem& elem);
static double fIC);
static void f2(double d);
};

#endif

Figure 6-47: New Insulating Utility Component e 1emut i 1

section 6.4.1 The Protocol Class 397

The modified system is illustrated in Figure 6-48. Public clients of the new E1em pro-
tocol will now be relieved of all the compile-time coupling formerly associated with
E1 em. All of this tight coupling has been completely isolated within the element sub-
system.

Figure 6-48: Using the New InSUlating E1 em Base Class

398 Insulation Chapter 6

By providing a separate utility component with create functions to instantiate each

derived class, we can continue to insulate all of our public clients from all of the com..
plex implementation details in the E1 em class hierarchy. This insulation applies even
to clients (such as eli en t 1) that endeavor to create new instances of types derived
from E1 em. Derived classes, however, continue to be at the mercy of any uninsulated
changes in the E1 emlmp base class. Note that clients of derived classes providing
"extra" functionality (Le., functionality beyond what is accessible through the E1em
protocol) unfortunately will be forced to depend on the derived class (and therefore on
el emimp) at compile time.

6.4.2 The Fully Insulating Concrete Class

A concrete class is more than just an interface-it defines a useful object that can be
instantiated as an automatic variable on the program stack. Protocol classes (dis-
cussed in Section 6.4.1) are consistent with pure object-oriented design; however,
engineering is anything but pure. Sometimes we would like the insulating benefits of
having a protocol and yet be able to construct an instance of the object Gust like any
other concrete class).

Consider the class Examp 1 e shown in Figure 6-49. This class contains, as embedded
data members, the use~-defined types A, B, and C. All member functions are implicitly
declared i n 1 i ne and the . c file is essentially empty. The implementation of this class is
clearly not insulated from clients. Suppose we now realize that this class is going to be
used widely and that the implementation is subject to change. What can we do to insu-
late our clients from changes to the implementation details in our example component?
section 6.4.2 The Fully Insulating Concrete Class 399

I I e xamp 1e ..h
#ifndef INCLUDED EXAMPLE
#define INCLUDED_EXAMPLE

#ifndef INCLUDED_A
#include "a.h"
fIend if

#ifndef INCLUDED_B
#include "b.h"
Ifendif

#ifndef INCLUDED_C
#include "c.hn
ffendif

class Example {
A d_a;
B d_b;
Cdc'
- ,
double value2() canst { return d_a.valueC) + d_b.valueC); }

public:
Examp 1 e () {}
Example(canst Example& e) : d_aCe.d_a), d_bCe.d_b), d cCe.d c) {}
-Examp 1e () {}

Example& operatar=(const Example& e)

{
d_a - e.d_a;
d b - e.d_b;
d c - e.d_c;
return *this;
}

double value() const

{
return value2() + d_c.valueC);
}
};

#endif
II example.c
#include "example.h h

Figure 6-49: Component Containing a Non-Insulating Concrete Class

400 Insulation Chapter 6

The fITst step is to replace all embedded data with an outwardly opaque pointer to
hold that data. By removing the embedded instances, we eliminate the need of Our cli-
ents to have seen the definitions of classes A, B, and C. We can therefore remove the
explicit #include directives from example.h and replace them with class declara-
tions. Doing so will often require defining previously inline functions out of line,
which is entirely consistent with our desire to insulate.

Figure 6-50 shows how this transform would look for the examp 1 e component. As the
figure shows, the . h file is smaller and the . c file is no longer empty. Clients of com-
ponent examp 1e are now insulated from all implementation-and even interface-
changes to components a, b, and c.
Section 6.4.2 The Fully Insulating Concrete Class 401

II example.h .
#ifndef INCLUDED_EXAMPLE
#define INCLUDED_EXAMPLE
II example.c
class A; #include "example.h"
class B; #include "a.h"
class C; #include Itb.h"
tfinclude "c.hlt
class Example {
A *d_a_p; Example::ExampleC)
B *d_b_p; d_a_pCnew A)
C *d_c_p; , d_b_pCnew B)
double value2C) const; , d_c_pCnew C)
{}
public:
Exampl eC); Example::ExampleCconst Example& example)
ExampleCconst Example& example); d_a_pCnew AC*example.d_a_p))
,."ExampleC); , d_b_pCnew BC*example.d_b_p))
, d_c_pCnew CC*example.d_c_p))
Example& operator=Cconst Example&); {}

double valueC) canst; Example::-ExampleC)

}; {
delete d_a_p;
trend if delete d_b_p;
delete d_c_p;
}

Example& Example::aperatar=(const Example& e)

{
if (&example != this) {
delete d_a_p;
delete d_b_p;
delete d_c_p;
d_a_p = new AC*e.d_a_p);
d_b_p - new B(*e.d_b_p);
d_c_p = new C(*e.d_c_p);
};
return *this;
}

double Example::value2() canst

{

double Example::valueC) canst

{
return value2C) + d_c_p->valueC);
}

Figure 6-50: Component Containing a Partially Insulating Concrete Class

402 Insulation Chapter 6

However, our clients are not entirely insulated from changes to the implementation of
the examp 1e component itself. Specifically, clients of examp 1 e are not insulated from
the actual number of outwardly opaque pointers contained in the Exampl e class defi-
nition. Adding a single instance of even a fundamental type to the private data of class
Examp 1e would force all of its clients to recompile. Modifying the signature or return
type of any private member function would have the same effect.

Holding only a single opaque pointer to a structure containing all of a

class's private members enables a concrete class to insulate its imple-
mentation from its clients.

How can we completely insulate the implementation of class Examp 1 e and still have it
remain a concrete class? The answer centers around getting rid of the individual pri-
vate data members and replacing them with a single opaque pointer to the class's rep-
resentation. 14

.
DEFINITION: A concrete class is/ully insulating if it
1. contains exactly one data member that is an outwardly opaque
pointer to a non-canst struct (defined in the. c file) specifying the
implementation of that class,
2. does not contain any other private or protected members of any
kind,
3. does not inherit from any class, and
4. does not declare any virtual or inline functions.

14 murray, Section 3.3, pp. 72-74.

section 6.4.2 The Fully Insulating Concrete Class 403

II example.h
#ifndef INCLUDED EXAMPLE
#define INCLUDED_EXAMPLE
class Example_i: II fully insulated implementation
class Example {
Example_i *d_this;

public:
ExampleC);
Example(const Example& example):
-Example();
Example& operator=Cconst Example& example);
double valueC) canst;
}

fIend if II example.c
#include Hexample.h"
#include "a.hH
#include nb.h"
#include "c.h"

struct Example_i {
Ada·
-
B db'
.
.
- ~

Cdc·_ t

double value2C) const { return d_a.valueC) + d_b.value(); }

}

Example::ExampleC) : d thisCnew Example_i) {}

Example::ExampleCconst Example& example)

: d_thisCnew Example_iC*example.d_this» {}

Example::-Example() { delete d_this; }

Example& Example::aperator=(const Example& example)

{
*d_this = *example.d_this;
return *this;
}

double Example: :valueC) const

{
return d this->value2C) + d_this->d_c.valueC);
}

Figure 6-51: Component Containing a Fully Insulating Concrete Class

404 Insulation Chapter 6

Figure 6-51 illustrates the result of transforming a class that does not insulate its cli-
ents from any of its implementation details to one that is fully insulating. All public
inline functions are eliminated. All private member data and functio~s are now made
part of an auxiliary s t ruct, defined entirely within the component's. c file. Note that,
in this example, the default member-wise copy semantics for the auxiliary s t ruct
happened to be correct and therefore were not implemented explicitly.

The physical structures of all fully insulating classes appear out-

wardly to be identical.

The important property of a fully insulated class is that changing its representation
does not affect how clients perceive the physical layout of an instance, because its
implementation (object layout) is always just a single opaque pointer. An instance of
one fully insulating class looks the same as every instance of every other fully insulat-
ing class, regardless of its purpose or functionality. It is this property of physical uni-
formity that enables the arbitrary reimplementation of the class's interface without
having to alter its header file in any way.

Allowing inheritance or virtual funcrions would affect the object layout by introduc-
ing additional data and/or additional virtual-function-table pointers. Note that inherit-
ing from even an empty s t rue t may affect the size of the derived object. Thus an
instance of an otherwise fully insulating class that inherits from a base class would
necessarily appear physically different from an instance of a fully insulated class that
does not. In other words, inheriting from a base class would increase the size of a fully
insulating class beyond that of a single pointer, physically distinguishing its instances
from those of other, fully insulating classes.

All fully insulated implementations can be modified without affecting

any header file.
Section 6.4.3 The Insulating Wrapper 405

Another important property of being fully insulating is that the class has sole control
over and access to the s t r uc t defining its internal representation. Letting the internal
data member point directly at an instance of a class defined in a separate component
would compromise our ability to make independent insulated changes to our own
implementation. In order to add a private member without affecting our clients, we
would be forced to alter the interface of an independently accessible, independently
testable object.

When writing the implementations of member functions for a fully insulating

concrete class, instead of relying on the implicit notation:

d_c to mean thi s->d_c

val ue 2 () to mean t his - >val ue 2 ( )

we must now use the d_thi s pointer explicitly as follows:

d_c becomes d_this->d_c;

value2() becomes d_this->value2();

The name of the data structure type (e.g., Examp 1 e_ i) and especially the name of the
instance variable (e.g., d_thi s) are mostly a matter of style and need not be the same
in all cases. Because the Ex amp 1 e_ i s t r uc t ("hidden" in the . c file) may contain
function or static data members with external linkage, however, there is the possibility
for unexpected link-time collisions with members of like-named classes defined out-
side this component. For this reason, the naming convention for the s t r u c t defining
the fully insulated implementation should be disjoint from that for naming ordinary
classes. Adopting the prefix of the publicly accessible class name followed by an
underscore ensures that an implementation class local to a component will not collide
with classes defined outside this component. You may find this kind of consistent
convention helpful for identifying the representation of fully insulating classes when
working on large projects.

6.4.3 The Insulating Wrapper

Wrappers were presented in Section 5.10 as a general encapsulation technique that

applies not just to individual components but to entire subsystems. Instead of attempting
to encapsulate within each component what would appear to a user of the subsystem as
406 Insulation Chapter 6

an implementation detail, we introduced wrapper components to encapSUlate the use

of these implementation components.

Because clients of a subsystem were not granted programmatic access to objects

defined in the lower-level implementation components, we were able to force these
clients to interact with the subsystem exclusively through the wrapper interface.

Here we propose to make the wrapper not only encapSUlating but insulating as well.
We therefore endeavor to eliminate the unnecessary clutter and compile-time coupling
associated with an interface that contains irrelevant or perhaps even proprietary infor-
mation.

6.4.3.1 Single-Component Wrappers

One way to produce an insulating wrapper component is to apply the total insulation
technique of Section 6.4.2 to the individual objects defined in an encapsulating wrap-
per. We can do this without affecting any of the lower-level objects used to implement
the wrapper.

client code

clients

-----t~---
graph
subsystem

Figure 6-52: Component Dependency of Graph Wrapper from Figure 5-95

Section 6.4.3.1 Single-Component Wrappers 407

Figure 6-52 shows the component dependency for the graph wrapper component of
Figure 5-95. As you may recall, the clients of graph were not permitted to access the
objects defined in the implementation components: graphimp, gnode, gedge, and
ptrbag. However, clients of graph were not insulated from changes to the headers of
these components.

Let us consider insulating the graph wrapper component of Figure 5-95. A brute-
force conversion of graph using the total insulation technique of Section 6.4.2 pro-
duces the header file shown in Figure 6-53. This interface does achieve total insula-
tion, but it is at a significant cost in runtime performance due to extra dynamic
memory allocations.

II graph.h
#ifndef INCLUDED_GRAPH
#define INCLUDED_GRAPH

class Node: II used in the interface of graph

class Edge; II used in the interface of graph
class Node I d_ i ; II should be changed to: class Gnode:
class Edge I d_ i ; II should be changed to: class Gedge;
class Graph_i; II fully insulated implementation
class Nodelter_i: II fully insulated implementation
class Edgelter_i: II fully. insulated implementation

class NodeId {
Nodeld_i *d_this; II should be changed to: Gnode *d_node_p;
friend Edgeld;
friend Graph:
friend Nodelter;
friend Edgelter;

public:
Nodeld();
Nodeld(const NodeId& nid);
. . . Nodeld();
Nodeld& operator=(const Nodeld& nid);
operator Node *() canst;
Node *operator->() const;
};

class Edgeld {
Edgeld_i *d_this; II should be changed to: Gedge *d_edge_p;
friend Graph;
friend EdgeIter;
408 Insulation Chapter 6

public:
Edgeld();
Edgeld(const Edgeld& eid);
-Edgeld();
Edgeld& operator=Cconst Edgeld& eid);
Nodeld from() const;
Nodeld toC) const;
operator Edge *() const;
Edge *operator->() const;
};

class Graph {
Graph_i *d_this;
friend Nodelter;
friend Edgelter;

private:
Graph(const Graph&); II not implemented
Graph& operator=(const Graph&); II not implemented

public:
Graph();
-Gra ph ( ) ;
Nodeld addNode(const char *nodeName);
Nodeld findNode(const char *nodeName);
void removeNode(const Nodeld& nid);
Edgeld addEdge(const Nodeld& from, const Nodeld& to, double weigh·t);
Edgeld findEdge(const Nodeld& from, canst Nodeld& to);
void removeEdge(const Edgeld& eid);
};

class Nodelter {
Nodelter_i *d_this;

private:
Nodelter(const Nodelter&);
Nodelter& operator=(const Nodelter&);

public:
Nodelter(const Graph& graph);
. . . NodelterC);
void operator++();
operator const void *() const;
Nodeld operator()() const;
};

class Edgelter {
Edgelter_i *d_this;
section 6.4.3.1 Single-Component Wrappers 409

private:
Edgelter(const Edgelter&);
Edgelter& operator=(const Edgelter&);

public:
EdgeIter(const Graph& graph);
EdgeIter(const Nodeld& nid);
-Edgelter():
void operator++();
operator const void *() const;
EdgeId operator()() const;
};

#endif

Figure 6-53: Header for Fully Insulating 9 rap h Wrapper Component, 9 rap h . h

As Figure 6-54 shows, the fully insulating version of class Node I d now requires
dynamic allocation whenever a Nodeld is returned by value:

NodeId Graph::findNode(const char *nodeName)

{
NodeId id; II causes dynamic allocation
id.d_this-)d_node_p = d_this-)d_imp.findNode(nodeName);
return id;
}
410 Insulation Chapter 6

II (from graph.h)

class NOdeld_i; II fully insulated

class Nodeld {
NodeId_i *d_this;
friend EdgeId;
friend Graph; II (from graph.c)
friend NodeIter;
friend EdgeIter; struct NodeId_i {
Gnode *d_node_p;
public: };
NodeId();
Nodeld(const NodeId& nid); NodeId::NodeId()
~Nodeld(); {
NodeId& operator=(const NodeId&): d_this = new NodeId_i;
operator Node *() const; d_this->d_node_p = 0;
Node *operator->() const; }
};
NodeId::Nodeld(const Nodeld& nid)
{
d_this = new NodeId_i;
d_this->d_node_p = nid.d_this->d_node_p;
}

Nodeld::~NodeId()
{
delete d_this;
}

NodeId& NodeId: :operator=(const Nodeld& nid)

{
d_this->d_node_p = nid.d_this->d_node_p;
return *this:
}

NodeId::operator Node *() canst

{
return d_this->d_nade_p;
}

Node *NodeId::operator->() canst

{
return *this;

Figure 6-54: Fully Insulated Reimplementation of Nod e I d from Figure 5-95

section 6.4.3.1 Single-Component Wrappers 411

Instead of insisting on total insulation for all of the wrapper classes, we can achieve
most of the advantages of insulation at considerably less runtime cost if we only par-
tially insulate the NodeId and Edgeld classes. By exposing just the names of these
implementation classes in the wrapper header, we give up the flexibility to add inde-
pendent members to the wrapper classes; however, we retain the right to modify the
organization of Gnode and Gedge in any way we see fit.

II (from graph.h)

class Gnode; II partially insulated

class Nodeld {
Gnode *d_node_p;
friend Edgeld;
friend Graph; II (from graph.c)
friend Nodelter;
friend Edgelter; Nodeld: : Nodeld() : d_node_p( 0) {}

public: Nodeld::NodeldCconst Nodeld& nid)

Nodeld() ; : d_node_pCnid.d_node_p) {}
Nodeld(const Nodeld& nid);
. . . Nodeld(); Nodeld: : . . . Nodeld() {}
Nodeld& operator=(const Nodeld&);
operator Node *() const; Nodeld& Nodeld::operator=Cconst Nodeld& nid)
Node *operator-)() const; {
}; d_node_p = nid.d_node_p;
return *this;
}

Nodeld::operator Node *() const

{

Node *Nadeld::aperator-)() canst

{
return *this;
}

Figure 6-55: Partially Insulated Reimplementation of Nodeld from Figure 5-95

Figure 6-55 demonstrates how one can temper total insulation for lightweight classes to
improve performance. Functions returning Nodeld by value can now do so without the
cost of allocating dynamic memory-a cost we attempt to quantify in Section 6.6.1:
412 Insulation Chapter 6

Nodeld Graph::findNode(const char *nodeName)

{
Nodeld id; II no dynamic allocation here
id.d_node_p = d_this->d_imp.findNode(nodeName);
return id;
}

Although the runtime performance stands to benefit significantly from the partial
insulation of Node I d and Edge I d, the remaining three classes-Gra ph, Node I ter, and
Edge I te r-are an entirely separate matter. In each case, insulating the client of the
wrapper from the implementation object requires a dynamic allocation anyway. It
costs no more at runtime to allocate a s t rue t containing the implementation object
than it does to allocate the implementation object itself. Nor is there any additional
runtime cost associated with extra indirection. We have to follow exactly one
pointer-adding a theoretical offset of 0 is removed by standard compile-time optimi-
zation. In terms of performance, fully insulating these classes costs no more than par-
tially insulating them, so we might as well go for it.

Notice also that Graph, Nodelter, and Edgelter have each disabled both copy con-
struction and assignment. Because the normal use of these objects requires creating and
destroying them much less frequently than Note I d and Edge I d, they are naturally better
candidates for insulation. The fully insulated implementations of Gra ph, Node I ter, and
Edgelter, along with the partially insulated implementations of Nodeld and Edgeld
corresponding to the suggested changes in the header file of Figure 6-53, are provided
for reference in Figure 6-56.

II graph.c
#include "graph.h"
#include "graphimp.h"
Ifinclude "gnode.h"
#include "gedge.h"

Nodeld::Nodeld() : d_node~p(O) {}

Nodeld::Nodeld(const Nodeld& nid) d_node_p(nid.d_node_p) {}

Nodeld: :'"'"'Nodeld() {}

Nodeld& Nodeld::operator=(const Nodeld& nid)

{
d_node_p = nid.d_node_p:
return *this;
}
section 6.4.3.1 Single-Component Wrappers 413

Nodeld::operator Node *() canst { return d_node_p; }

Node *Nodeld::operator->() const { return *this; }

Edgeld::Edgeld() : d_edge_p(O) {}

Edgeld::Edgeld(const Edgeld& eid)

Edgeld: : . . . Edgeld() {}

.Edgeld& Edgeld::operator=(const Edgeld& eid)

{
d_edge_p = eid.d_edge_p;
return *this;
}

Nodeld Edgeld::from() const

{
Nodeld id;
id.d_node_p - d_edge_p->from();
return id;
}

Nodeld Edgeld::to() const

{
Nodeld id;
id.d_node_p - d_edge_p->to();
return id;
}

Edgeld::operator Edge *C) const { return d_edge_p: }

Edge *Edgeld::operator->() canst { return *this; }

struct Graph_i {
Graphlmp d_imp;
};

Graph: :Graph() : d_thisCnew Graph_i) {}

Graph::~Graph() { delete d_this; }

Nodeld Graph::addNode(const char *nodeName)

{
Nodeld id;
id.d_node_p - d_this->d_imp.addNode(nodeName);
return id;
}
414 Insulation Chapter 6

Nodeld Graph::findNode(const char *nodeName)

{
Nodeld id;
id.d_node_p - d_this-)d_imp.findNode(nodeName);
return id;
}

void Graph::removeNode(const Nodeld& nid)

{
d_this-)d_imp.removeNode(nid.d_node_p);
}

Edgeld Graph::addEdge(const Nodeld& from, canst Nodeld& to, double weight)

{
Edgeld id;
id.d_edge_p - d_this-)d_imp.addEdge(from.d_node_p, to. d_node_p , weight);
return id;
}

Edgeld Graph::findEdge(const Nodeld& from, const Nodeld& to)

{
Edgeld id;
id.d_edge_p - d_this-)d_imp.findEdge(from.d_node_p, to.d_node_p);
return id;
}

void Graph::removeEdge(const Edgeld& eid)

{
d_this-)d_imp.remaveEdge(eid.d_edge_p);
}

struct Nodelter i {
GnodePtrBaglter d_iter;
Nodelter i(const GnodePtrBag& nodes) d_iter(nodes) {}
};

Nodelter::Nodelter(const Graph& graph)

: d_this(new Nodelter_i(graph.d_this-)d_imp.nodes(») {}

Nodelter::-Nodelter() { delete d_this; }

void Nodelter::operator++() { ++d_this-)d_iter; }

NodeIter::operator const void *() canst { return d_this-)d_iter; }

Nodeld Nodelter: :operator()() const

{
Nodeld id;
id.d_node_p - d_this-)d_iterC);
return id;
}
section 6.4.3.2 Multi-Component Wrappers 415

struct Edgelter_i {
GedgePtrBaglter d_iter;
Edgelter_;(const GedgePtrBag& edges) d_iter(edges) {}
};

Edgelter::Edgelter(const Graph& graph)

: d_this(new Edgelter_i(graph.d_this->d_imp.edges())) {}

Edgelter::Edgelter(const Nodeld& nid)

: d_this(new Edgelter_i(nid.d_node_p->edges())) {}

Edgelter::~Edgelter() { delete d_this; }

void Edgelter::operator++() { ++d_this->d_iter: }

Edgelter::operator const void *() const { return d_this->d_iter; }

Edgeld Edgelter: :operator()() const

{
Edgeld id;
id.d_edge_p = d_this->d_iter();
return id;
}

Figure 6-56: Almost Fully Insulated Reimplementation of graph (g ra ph . c)

If designed properly, a single wrapper component can effectively insulate clients from
the organizational details of many lower-level implementation components.

6.4.3.2 Multi-Component Wrappers

Wrapping components individually is also possible, but only when direct interaction
with the underlying component by clients is not required. As an instructive (but
unlikely) example, consider creating the fully insulating wrapper component
pubs tack for a non-insulating, list-based stack component.

As illustrated in Figure 6-57, the original s t a c k component exposes three classes and
two operators in its header file. One of these classes, St ac k Lin k, is an encapsulated
implementation detail of the other two classes (S t a c k and St a c kIt e r). The wrapper
component, pubstack, exposes two classes, two free operators, and none of the
underlying implementation details. Regardless of how St a c k and St a c kIt e r are
implemented, clients of the wrapper classes are insulated from all implementation
details.
416 Insulation Chapter 6

pubstack stack

Figure 6-57: Complete Component/Class Diagram for stack and Its Wrapper

Figure 6-58 shows the header file for a fully insulating wrapper for a stack compo-
nent. Each of the two wrapper classes holds only a single private opaque pointer to its
own internally defined implementation structure. There are no other private or pro-
tected members of any kind in the wrapper's physical interface. All functions will be
defined out of line. The friendships necessary to extract the underlying wrapped
objects from other wrapper objects passed as parameters are the only implementation
details in the physical interface of this wrapper component.

II pubstack.h
#ifndef INCLUDED_PUBSTACK
#define INCLUDED_PUBSTACK

class PubStacklter;

class PubStack_i;
class PubStack {
PubStack_i *d_this;
friend PubStacklter;
II May want to grant access to improve performance andlor reuse:
Ilfriend int operatar==(const PubStack&, canst PubStack&);
section 6.4.3.2 Multi-Component Wrappers 417

public:
PubStack();
PubStack(const PubStack& stack);
-PubStack();
PubStack& operator=(const PubStack& stack);
void push(int value);
int pope);
int tope) const;
int isEmpty() const;
};

int operator==(const PubStack& left, const PubStack& right);

int operator!=(const PubStack& left, canst PubStack& right);

class PubStacklter_i;
class PubStacklter {
PubStacklter_i *d_this;
PubStacklter(const PubStacklter&);
PubStackIter& operatar=(canst PubStacklter&);

public:
PubStacklter(const PubStack& stack);
""'PubStacklter();
void operator++();
operator canst void *() canst;
int operator()() canst;
};

#endif

Figure 6-58: Fully Insulating stack Wrapper Interface (pubstack. h)

Figure 6-59 shows how the pubstack component is implemented. Virtually all func-
tionality supplied by Pub St a c k forwards calls out of line to the corresponding func-
tions of the insulated implementation object, St ac k. Each constructor of Pub St a c k
merely allocates an instance of its auxiliary structure, Pub St a c k_ i. Pub St a c k' s
destructor destroys this dynamically allocated instance, and all member functions
simply forward their input to the corresponding members of the St a c k object embed-
ded in the managed instance of Pub St ac k_ i .
418 Insulation Chapter 6

II pubstack.c
#include "pubstack.h"
#include "stack.h"

struct PubStack_i {
Stack d_stack;
};

PubStack::PubStack()
d_this(new PubStack_i) {}

PubStack::PubStack(const PubStack& s)
d_this(new PUbStack_i(*s.d_this)) {}

PubStack::~PubStack() { delete d_this; }

PubStack& PubStack::aperator=(const PubStack& s)

{
*d - this = *s.d-
this·
,
return *this;
}

void PubStack::push(int v) { d_this->d_stack.push(v); }

int PubStack::pap() { return d_this->d~stack.pop(); }

int PubStack::top() canst { return d_this->d_stack.top(); }

int PubStack::isEmpty() c9nst { return d_this->d_stack.isEmpty(); }

int operator==(canst PubStack& left, canst PubStack& right)

{
PubStacklter lit(left);
PubStacklter rit(right);
for (; lit && rit; ++lit, ++rit) {
if (lit() != rite)) {
return 0;
}
}
II at least one of lit and rit is now 0
return lit == rit;
}

int operatar!=(const PubStack& left, const PubStack& right)

{
return !(left == right);
}

struct PubStacklter_i {
Stacklter d_stacklter;
PubStacklter_i(Stack &stack) d stacklter(stack) {}
};
section 6.4.3.2 Multi-Component Wrappers 419

PubSta~klter::PubStacklter(const PubStack& stack)

: d_this(ne~ PubStacklter_iCstack.d_this->d_stack)) {}

PubStacklter::-PubStacklter() { delete d_this; }

PubStacklter::operator canst void *() canst

{
return d_this->d_stacklter.operator canst vaid*();
}

int PubStacklter::aperatar()() const

{
return d_this->d_stacklter.aperator()();
}

Figure 6-59: Implementation of Fully Insulating 5 t a c k Wrapper, pub 5 t a c k . c

In this example, the free operator== does not absolutely need to have access to the
private implementation of the underlying subobject in order to implement its func-
tionality. Instead ope ra to r== can implement its functionality locally via the public
version of the iterator, which does have private access to the underlying implementa-
tion. If this overhead is deemed excessive, it is easy enough to declare the wrapper
function

int operator==Ccanst PubStack& left. canst PubStack& right)

a friend of class Pub St a c k. Doing so would grant this free operator private access to
PubStack's underlying Stack object, enabling it to invoke the corresponding, lower-
level operator== directly:

int op~rator==Cconst PubStack& left. canst PubStack& right)

{

Anticipating the possibility of this optimization, we might choose to declare all

classes and free operators that use Pub St a c k in their interface to be friends of
PubStack, thereby granting them direct access to its underlying representation object,
St a c k. For complete wrapper layers that fit within a single component (e.g.,
p2p_router, pubstack, graph), this approach is quite workable. Any implied friend-
ships are all local to a single component and therefore neither impose additional cou-
pling nor threaten encapsulation.
420 Insulation Chapter 6

There is no way to determine programmatically from outside a com-

ponent whether that component is or is not a wrapper.

Because a wrapper fully encapsulates its underlying implementation, it is not in gen-

eral practical to wrap individual components. If we were to attempt to insulate a large
subsystem using individual wrapper components in a way that tried to mirror the
underlying implementation, the need for long-distance friendships would quickly
become apparent.

Figure 6-60 illustrates the problem with wrapping components that have to interact
directly. An E1 emSet is an object that manages a collection of objects of type E1 em.
E1emSet has a member, vo ida dd (con s t E1 em&), that takes an element and adds a copy
of its value to the set PubE1 emSet has a similar member, voi d add (cons t PubE1 em&),
which instead takes a PubEl em and adds a copy of its value to the set How would you
propose to implement pubE1 emSet: : add? The only obvious implementation

void pubElemSet::add(const PubElem& elem)

{
d_this-)d_elemSet.add(elem-)d_this.d_elem);
}

forces the higher-level PubE1 emSet to be a long-distance friend of PubE1 em, which
(see Section 3.6) is a breach of encapsulation.

Figure 6-60: The Difficulty with Wrapping Individual Components

section 6.4.3.2 Multi-Component Wrappers 421

Forgetting for the moment the inherent problems with long-distance friendships, the
sheer number of required friendships will quickly prove this strategy to be unwork-
able. Each wrapper type that is used as an argument to a wrapper class member (or
free operator) must declare that class or operator a friend in order to allow it access to
the underlying representation object being passed. As illustrated in Figure 6-61, two
wrappers, PubA and PubB, are currently used in the public interface of PubX. PubC, for-
merly not used by PubX, is in the signature of a member about to be added to PubX. As
the figure shows, adding the member function vai d h (canst PubC& c) to a higher-
level class, PubX, can force a fri end declaration to be added to a lower-level class
definition, PubC. This modification in turn forces that class, along with all of its
clients, to recompile!

add this? ~clients of PubC ~

• • •

class PubA;
class PubS;
Ilclass PubC;
class PubX { if we add these,
X *d_imp_p; then we'll be
forced to add
public: these too!
void f(const PubA& a);
void g(const PubB& b);
Ilvoid h(const PubC& c);
};

class PubX; class PubX; Ilclass PubX;

class PubA { class PubB { ·cl ass PubC {
A *d_imp_p; B *d_imp_p; C *d_imp_p;
friend PubX; friend PubX; Ilfriend PubX;

public: public: public:

II ... I I ... II ...
}; }; };

Figure 6-61: Two-Way Coupling Caused by the Uses Relation Among Wrappers
422 Insulation Chapter 6

Whenever a type defined in one wrapper component is passed into a

type defined in a second wrapper component, that second component
will be unable to access the underlying wrapped implementation
object(s); only the public functionality of the wrapper will be available.

Nonetheless, with careful design it is possible and very useful to create mUlti-compo-
nent insulating wrappers. The secret to creating such a wrapper layer is to realize that
only classes and operators within a single component can legitimately take advantage
of what goes on below the interface of that component, via friendships.

Consider the component/class diagram in Figure 6-62. The low-level subsystem

implementation is not only encapsulated-it is also insulated from the rest of the sub-
system's clients by a relatively small number of wrapper components. In this architec-
ture, each of the wrapper components respects the privacy of the implementation of
every other component (wrapper or otherwise), and limits its access to their public
interfaces. To do anything else would violate the encapsulation that we are trying to
achieve in this architecture.

Wrapper objects defined within a single wrapper component are at liberty to employ
friendship as needed to look below the local interfaces and manipulate the underlying
representation directly. For example, suppose in Figure 6-62 that (as with E1 emSet
and E1 em), class E uses class B in its interface and we want to expose a public version
of both E and B to clients. Class Pub E will need private access to obtain the instance of
B encapsulated within PubB. We are forced to declare PubE a friend of PubB, making it
necessary to place both PubB and P.ubE in the same wrapper component to preserve
encapsulation. 15

15 This technique should not be construed as a general panacea for avoiding long-distance friend-
ships among non-wrapper classes. Since wrapper classes are typically simple in nature, merging
several of them in a single component does not necessarily threaten effective testability. Merging the
implementation components, for example, would defeat the goals of designing a hierarchy of indi-
vidual components, each with manageable complexity_
Section 6.4.3.2 Multi-Component Wrappers 423

Wrapper
(Interface)
Layer

--------------------

Subsystem
(Implementation)
Layer

w x y z
Figure 6-62: Creating an Insulating, Multi-Component Wrapper
424 Insulation Chapter 6

The design goal of avoiding long-distance friendship makes it normal for wrapper-
layer components to be much larger and define significantly more objects than is typ-
ical of components in the underlying, low-level implementation. In particular, the
component containing the PubG wrapper in Figure 6-62, like the graph wrapper com-
ponent of Section 6.4.3, supplies additional iterator classes to provide clients with
insulated access to lower-level functionality.

This type of encapsulating and insulating subsystem architecture is extremely power-

ful. As with the encapsulating wrapper discussed in Section 5.10, we are able to
impose policy by reducing direct public access to the underlying functionality. Since
the insulation also occurs at a higher level, there is no need to insulate the low-level
subsystem components individually. In these lower-level components, we may feel
free to take advantage of tight compile-time coupling to improve performance. For
instance, inline functions are commonly used to access scalar data, and objects are
often embedded within other objects to avoid the overhead of dynamic allocation. In
short, the impact of compile-time coupling has been dealt with "upstream" at the
higher levels of the subsystem.

Wrapper components themselves are often large in order to enforce encapsulation;

however, they need not be complex. One important function of a wrapper component
is to delegate and coordinate complex tasks-not to perform them itself. The complex
functionality implemented in the lower-level components can be tested and reused
independently. Testing the wrapper should be little more than verifying that the fully
tested, underlying components have been hooked up correctly. Although significant
overhead may be incurred when information is passed between the wrapper layer and
the low-level subsystem, choosing the appropriate level at which to insulate ensures
that the bulk of the interobject communication occurs below the wrapper level. If
done carefully, insulation need not impose a significant performance burden.

In summary, an insulating wrapper is also encapsulating. There is no place in the logi-

cal interface of the wrapper objects where types defined in the implementation compo-
nents are used. The encapsulation property of insulating wrappers allows independent
reuse of the underlying implementation components of a wrapped subsystem in other .
subsystems without any possibility of compromising the encapsulation of the wrapper.

If the wrapper insulation is complete, there is no place in the physical interfaces of the
wrapper components where the types defined in the implementation components are
section 6.5 The Procedural Interface 425

even named. A partially insulating wrapper may hold pointers to objects that are
themselves "first-class citizens" defined in separately accessible components. These
objects can be reused independently of the wrapper and are therefore less easily modified.

In contrast, a fully insulating wrapper merely holds a pointer to a simple s t rue t that
defines the private implementation in its . c file. Because there is no independent com-
ponent, there is no independent way to interact with the representation directly.
Unlike a partially insulating wrapper, it is possible to add arbitrary private data with-
out altering any header file.

In either case, the objects used to implement the wrapper are free to interact effi-
ciently via their own encapsulating (but usually non-insulating) interfaces at the
lower-levels of a subsystem.

Because of the potentially large number of interactions among components, it is often

not feasible to wrap the individual components of a subsystem. With careful planning,
however, it is possible to construct a multi-component wrapper for a subsystem. As
with all other components, only the public interface of wrapper components can be
accessible to other components. That is, only objects and operators defined within the
same wrapper component can access each other's underlying implementation.

6.5 The Procedural Interface

Often large commercial object-oriented systems (databases, frameworks, etc.) find it

necessary to supply their customers with programmatic access to a subset of the func-
tionality available to their own internal core system developers. For example, a data-
base may provide a high-level language interpreter (such as SQL or Scheme) to give
customers interactive access to the information in the database. Often a separate inter-
face is also provided to allow programs written by end users in C++ (or possibly even
ANSI C) to manipulate the database directly. Note that by end users we are envision-
ing clients who reside outside our company or organization.

The requirements of such a programmatic interface typically include the following:

• The interface must provide the necessary functionality to manipulate the

underlying system.

• The interface must not expose proprietary implementation details.

426 Insulation Chapter 6

• Changes to the underlying organization must be insulated from clients.

• The overhead associated with this interface must not be excessive.

If the interface is a C++ interface, then an insulating wrapper compone~t would be

ideal. Unfortunately, not every system can be wrapped. Some systems are just too
large for a set of wrapper classes to fit reasonably within a single component, and yet
are too tightly interconnected to permit a properly encapsulated implementation using
a multi-component wrapper. In short, if not explicitly designed as a wrapper already,
it may not be feasible to create an insulating wrapper layer for an existing system
without substantially altering its architecture.

If our primary goal is to insulate clients from everything that goes on underneath the
facade of an insulating layer for a very large and complex system, we will have to com-
promise. One such compromise is to give up the true logical encapsulation of a wrap-
per and rely on outwardly opaque pointers with unpublished header files to achieve the
encapsulation. This type of interface is commonly referred to as a procedural interface.

6.5.1 The Procedural Interface Architecture

The interface we are providing is typically much more abstract than those developers
used to create the implementation in the first place. For the same reasons discussed in
Chapter 4, it would be exceedingly difficult to ensure the reliability of such a system
by testing it from the procedural interface alone. Fortunately for us, however, the
complexity lies at the lower levels of the system. Our job as procedural-interface
authors is to identify an appropriate subset of the types and functionality already
defined in the lower-level implementation components that will allow end users to
accomplish their desired application-level tasks.

Figure 6-63 is an illustration of the way a procedural interface is organized. All of the
publicly accessible interface functions are independent of each other, and all of them
are at a higher level than every implementation component. There is no levelization
issue other than the fact that each individual interface function depends only on the
underlying implementation; the procedural-interface functions should not depend on
each other.
Section 6.5.1 The Procedural Interface Architecture 427

Procedural
Interface fl f4 f5 f6 f7 f8 f9 ... fn
Layer I \ I 1\ I \" 1\
\
---..----

Figure 6-63: Schematic Illustration of a Procedural Interface

If we were implementing an encapsulating/insulating wrapper component, then the

last thing we would want to do would be to expose the implementation types in the
interface of the wrapper. But independent reuse of our implementation components by
end users is likely to be irrelevant here. Forgoing independent reuse by customers is
what enables us to sacrifice the logical encapsulation afforded by wrapping.

If we decide to insulate using a procedural interface, then we will not incur the over-
head of creating new wrapper objects or be compelled to confine ourselves to a single
component to avoid long-distance friendships. We can simply expose an appropriate
subset of the underlying type names in the procedural interface without publishing
their definitions.

Note that the requirements here are not the same as they were in Section 5.10. There
our goal was to encapsulate the use of components; here our goal is to insulate clients
from the definitions of the objects we want them to use.

U sing the same type names as defined in the underlying implementation gives away
little information yet preserves the type safety across the interface. End users of this
428 Insulation Chapter 6

interface will benefit from the compiler-enforced type safety in their own applications
as well.

Besides reducing the overhead of additional classes and the compiler-enforced type
safety, exposing the underlying types in name may have a very appealing benefit for
marketing. Some customers may want to take advantage of the underlying object-ori-
ented organization of the system, and may be willing to pay extra for this privilege.
By providing these customers with a few key (protocol) base-class header files from
the underlying system, it is possible to enable them to derive their own special types
to be used within the system without exposing a single implementation detail.

Similarly, some customers may want better performance than an insulating procedural
interface can provide. By publishing the header files of just the lowest-level, concrete
objects (e.g., Poi nt, Box, Po 1ygon), preferred customers may create these objects as
automatic variables and access them directly via inline functions. It is by maintaining
type-name consistency across the procedural interface that all of this integration is
made seamless; notice how this would not be possible with an encapsulating wrapper.

6.5.2 Creating and Destroying Opaque Objects

For the purposes of this discussion, let's assume we are to create an ANSI C-compat-
ible interface. We therefore will be forced to use free functions-a necessary violation
of a major design rule from Chapter 2. To help avoid collisions in the global name
space, each of these free functions will begin with a consistent registered prefix (as
discussed in Section 7.2). The ANSI C language does not support C++ references, but
does support the notion of canst versus non-canst. Therefore all objects will be
passed by pointer, and only non-canst objects can be modified or destroyed.

Figure 6-64 depicts procedural-interface functions for creating and destroying a

Stack object such as the one defined in Figure 3-2. Once created, the Stack object
will remain in existence until the client explicitly destroys it with the type-safe
pi_des t roySta c k function.

/* CREATORS */
Stack *pi_createStack();
void pi~destroyStack(Stack *thisStack);

Figure 6-64: Procedural Interface for Creating an Opaque Stack Object

Section 6.5.3 Handles 429

ANSI C does not support the overloading of function names, which makes the naming
process problematic-particularly for constructors. Since objects created with a pro-
cedural interface cannot be automatic variables, their creation and destruction is dis-
proportionately more expensive than assignment. For these reasons, we may choose to
omit access to copy constructors, relying instead on the default constructor and
repeated use of the assignment operator.

The type safety afforded by ANSI C goes a long way toward protecting customers
from shooting themselves in the foot. Because this is a C and not a c++ interface,
however, there is also a greater danger that they may accidentally try to destroy some-
thing they did not allocate (and do not own), or try to destroy something they did allo-
cate, but do so more than once. A typical example of a common memory allocation
error is shown in Figure 6-65.

void f()
{
Stack *sl = pi_createStack();
Stack *s2 = pi_createStack();

/* ... */

pi_destroyStackCs1);
pi_destroyStack(sl);. /* Oops! */
}

Figure 6-65: The Ease of Corruption Memory in ANSI C

These kinds of customer errors are among the hardest to debug, and they· can be a
costly drain on a customer support organization. Fortunately there is an effective way
to detect most memory allocation errors. A memory allocator that has proven highly
effective at detecting and reporting memory allocation-related customer program-
ming errors in actual products is presented in Appendix B.

6.5.3 Handles

If we are creating a procedural interface to be used by customers writing in C++ (as

opposed to ANSI C), then there are better ways to handle dynamically allocated
objects than just returning a pointer. One popular approach to managing dynamically
allocated objects returned from functions involves a special kind of class commonly
referred to as a handle.
430 Insulation Chapter 6

DEFINITION: In this book, a handle is a class that maintains a

pointer to an object that is programmatically accessible through the
public interface of the handle class.

Basically, a handle is an object that is used to refer to another object. 16 Usually, a han-
dle holds a pointer to the "held" object but contains little else, as illustrated in Figure
6-66. Unlike a wrapper, the object to which the handle refers is programmatically
accessible from the interface of the handle. Handles used in this way are sometimes
called smart pointers. 17 There are many applications for the handle pattern in C++.
The Node I d wrapper class of Figure 5-95 acted as a handle for the Node portion of
Gnode object to which it held a pointer; Edgeld acted similarly.

d_stack_p C> d_array_p C>

pi_StackHandle
d_size

d_length
Stack ,.oJ . ~

int[d_size]

Figure 6-66: Object Diagram Dlustrating pi _StackHandl e and Stack Organization

A common way of managing a dynamically allocated object in C++ is to place its

address in a separate object whose job is simply to manage it. Such a manager object
is just a special type of handle object-a manager handle. The header file for a St ac k
manager handle is given in Figure 6-67.

16 stronstrup, Section 13.9, p. 460.

17 strollstrup, Section 7.9, p. 244.
Section 6.5.3 Handles 431

II pi_stackhandle.h
#ifndef INCLUDED_PI_STACKHANOLE
#define INCLUOED_PI_STACKHANDLE

class Stack:

class pi_StackHandle {
Stack *d_object_p;

private:
pi_StackHandle(const pi_StackHandle&); II not implemented
pi_StackHandle& operator=(const pi_StackHandle&); II not implemented
public:
c II CREATORS
pi_StackHandle();
""StackHandle();

II MANIPULATORS
void loadObjectCStack *stack); II Not intended for public use.

II ACCESSORS
operator Stack *() canst; II Conversion operator to allow use
}; II of this object as if this were
II a writable .pointer to a Stack.
#endif

Figure 6-67: A Manager Handle for Class Stack

Our overall approach to creating a procedural interface involving handles is illustrated

in Figure 6-68. Here, pi _S t a c k is just a s t rue t (defining a namespace) containing
only static member functions. These functions will serve as the C++ procedural inter-
face to manipulate St a c k objects, via outwardly opaque pointers.

Figure 6-68: Component/Class Diagram for a Procedural Interface with Handles

432 Insulation Chapter 6

II pi_stack.h
#ifndef INCLUDED- PI - STACK
#define INCLUDED- PI - STACK .,
/

I
r/
class Stack;

struct pi_Stack {
II CStack Creators)
static void createCpi_StackHandle *handleToBeLoaded);

II (Stack Manipulators)
static Stack *assignCStack *thisStack, canst Stack *thatStack):
static void pushCStack *thisStack, int value);
static int pop(Stack *thisStack);

II (Stack Accessors)
static int top(const Stack *thisStack) canst;
static int isEmpty(const Stack *thisStack) canst;
static int isEqual (const Stack *left, canst Stack *right) const;
};

#endif II pi_stack.c
#include "pi_stack.h"
#include "stack.h"

void pi_Stack::createCpi_StackHandle *h)

{
h-)laadObjectCnew Stack);
}

Stack *pi_Stack::assignCStack *thisStack, const Stack* thatStack)

{
*thisStack = *thatStack;
return thisStack;
}

void pi_Stack::pushCStack *thisStack, int value)

{
thisStack-)pushCvalue);
}

II

Figure 6-69: Procedural Interface Component pi_stack

Since we plan to use handles to manage memory, we will modify the stack creation
function Sta c k *pi _c rea teSta c k () that we used in ANSI C. In a handle-base archi ..
section 6.5.3 Handles 433

tecture, an equivalent C++ translation of this function will take a writable pointer to a
stack handle object as a parameter. We avoid the free functions of the ANSI C version
by making this function a static member of class pi _S t a c k. The header for the entire
pi_stack component is given in Figure 6-69.

Now, instead of returning a pointer to a dynamically allocated object directly, a

pi_StackHandl e object is first created by the client as an automatic variable. The
address of this handle is then passed into the c rea t e function, where it is loaded with
a dynamically allocated St a c k object, as shown in Figure 6-70. Once the handle is
loaded, its conversion operator allows the handle (see Figure 6-67) to be used as if it
were a pointer to a Stack.

v0 i d my Fun c ( )
{
pi_StackHandle h; II automatic variable
pi_Stack::create(&h); II load with dynamically allocated object
for Cint i = 0; i < 10; ++i) {
pi_Stack::pushCh, i); II push 0, 1 , ... , 9 on the managed stack
}
int x = pi_Stack::popCh); II pop 9 from managed stack into x
I I ...
}

Figure 6-70: Usage Model for a Manager Stack Handle

There is no need to implement a corresponding destroy function in the pi_Stack

interface. When the handle goes out of scope, the destructor of the handle in tum
destroys the contained (dynamically allocated) S t a c k object, as shown in Figure 6-71.

The scoping afforded by c++ classes and the ability to overload function names in C++
simplify the task of naming. Although the cosmetics of adding handles and scoping func-
tion names does not change the underlying nature of this interface-it is still procedural.

In particular, trying to make a handle look like a wrapper would be ill-advised. Con-
sider what would happen if, instead of the current interface, we implemented the pop
function as a non-static member of class pi _S t a c kHa nd 1e (taking no arguments):

class pi_StackHandle {
I I ...
public:
I I ...
int pope);
I I ...
}:
434 Insulation Chapter 6

II pi_stackhandle.h
#ifndef INCLUDED_PI_STACKHANOLE
#define INCLUDED_PI_STACKHANOLE

class pi_StackHandle {
Stack *d_stack_p; II pi_stackhandle.c
#include "pi_stackhandle.h"
public: #include "stack.h"
I I ...
-pi_StackHandle();
I I ...
I I ...
};
pi_StackHandle::-pi_StackHandle()
{
#endif
}

II

Figure 6-71: Destructor for Manager Handle Destroys Its "Held" Object

The obvious semantics would be that the pop ( ) member should pop and return the top
element of the St a c k object managed by this pi _S t a c kHan d 1 e. Suppose, however, we
are handed a pointer to a non-cons t Stac k that we do not own. How could we pop it?

If, as customers, all we had at our disposal is a pop ( ) member of class St a c kHan d 1 e,
we would be forced to use the loa dO b j e c t ( ) member to put this St a c k object pointer
inside a handle before we could manipulate it. But if we did that, we would now have
two agents managing the memory of the same Stack object!

The single purpose of the handle in a procedural interface is to manage the memory of
a dynamically allocated object. Except for the pi _S t a c k: : ere ate function, which
loads a pi_StackHandl e with a newly allocated Stack object, all of the functionality
defined in the pi _St a c k procedural interface should refer directly to the underlying
St a c k and not the pi _S t a c k Han d 1 e. By following this strategy, customers are never
forced, or even tempted, to abuse a handle to gain access to the functionality of the
underlying object.
section 6.5.4 Accessing and Manipulating Opaque Objects 435

6.5.4 Accessing and Manipulating Opaque Objects

Let us return to our assumption of ANSI C compatibility. A common hierarchical

naming convention for the analog of "member functions" in a procedural interface is
as follows: <prefix>_<Subject><Verb><Object>.

As a matter of consistency, it is desirable that our subject type (e.g., Stack) always
appear with an uppercase first letter. Ignoring the prefix, we want the actual function
name to comply with our design rule from Section 2.7 which suggests that all func-
tions begin with a lowercase letter. To lexically distinguish these global functions
from global types, we have inserted the letter f at the beginning of the actual function
name. For example,

i nt Stack:: pop ( ) : ~ i nt pi_fStackPop (Stack *);

double Angle: :getDegrees() canst; ~double pi_fAngleGetOegrees(const Angle *);
void List::append(const Elem&); ~vaid pi_fListAppendElem(List *. canst Elem *);

Although this style of naming is entirely appropriate for the procedural interface
layer, it does not necessarily translate directly to the underlying objects and member
functions of the implementation layer. For example, representing the conversion func-
tions (see Figure 5-15)

struct Convert {
static Window toWindow (canst Rectangle& r);
static Rectangle toRectangle (canst Window& w);
};

as

void pi_fRectangleGetWindow(const Rectangle *thisRect, Window *returnValue)

{
*returnValue = Convert::toWindaw(thisRect);
}

void pi_fWindowGetRectangle(const Window *thisWind, Rectangle *returnValue)

{
*returnValue = Convert::taRectangle(thisWind);
}

would be intuitive to procedural end users, and therefore an appropriate abstraction.

There is no levelization issue because each of these function depends only on imple-
mentation objects residing at lower levels in thq physical hierarchy. Yet, if realized as
member functions of the corresponding und~rlying implementation classes, this
436 Insulation Chapter 6

approach would quickly lead to an unlevelizable architecture. I sus'pect that naively try-
ing to map this kind of naming style onto C++ classes and their member functions is a
primary source of cyclic physical dependencies in many existing systems.

We now tum our attention to the class Shape shown in Figure 6-72. A bounding box is
a minimal rectangle consisting of horizontal and vertical edges that circumscribe a
collection of points. Every Shape, among other things, knows how to return (by value)
a bounding box of type Ba x that contains the Shap e.

class. Box;

Bounding Box class Shape {

// ...
public:
// ...
virtual Box bBax() canst;
// ...
};

Figure 6-72: Returning a User-Defined Type by Value

Because pointers are opaque, there can be no return by value for user-defined types in
a procedural interface. The obvious choice is to allocate a new Box and return a
pointer to it, as shown in Figure 6-73a. One problem with this approach is that objects
returned by value are typically small objects that do not have associated dynamic
memory. Dynamically allocating light-weight objects such as Box or Poi nt every time
one is accessed would create considerable unnecessary overhead. Another problem is
that returning unmanaged objects would make who owned what memory confusing
and increase the likelihood of leaks.
Section 6.5.4 Accessing and Manipulating Opaque Objects 437

Box *pi_fShapeGetBboxl(const Shape *thisShape)

{
return new BoxCthisShape-)bBox());
}

(a) Less Efficient, More Dangerous

void pi_fShapeGetBbox2(const Shape *thisShape. Box *returnValue)

{
*returnValue = thisShape-)bBox();
}

(b) More Efficient, Less Dangerous

Figure 6-73: Providing a Procedural Interface for Objects Returned by Value

In a procedural interface, having clients explicitly destroy only those

objects that they explicitly create reduces confusion over ownership
and can lead to improved performance.

We can avoid both the runtime overhead and confusion about ownership by sticking to
the simple principle that only the objects explicitly allocated by the client of a proce-
dural interface can be destroyed by that client-all other objects are owned and man-
aged by the system. The preferred procedural interface function is indicated in Figure
6-73b.
 438 Insulation Chapter 6

The improvement in runtime efficiency in Figure 6-73b can be significant. Figure 6.. 74
shows two implementations of a function that returns the sum of the area of the
bounding boxes for an array of shapes. For small, lightweight objects, such as Point or
Box, that are obtained over and over in a single function, the cost of dynamic alloca-
tion and deallocation on every iteration of the loop (Figure 6-74a) could easily domi-
nate the runtime cost of the function call. Instead, we can do the allocation once
outside the loop (Figure 6-7 4b) and then reuse the allocated object over and over,
reSUlting in a dramatic improvement in runtime efficiency.

double sumArealCconst Shape *shape[], double sumArea2(const Shape *shape[],

int size) int size)
{ (
double sum = 0; double sum = 0;
i nt i; Box *box = pi_createBox();
for Ci = 0; i < size; ++i) { i nt 1;
Box *box = pi_fShapeGetBboxl(shape[i]); fa r Ci = 0; i < s i z e; ++i) {
sum += pi_fBoxGetAreaCbox); pi_fShapeGetBbox2Cshape[i], box);
pi_destroyBoxCbox); sum += pi_fBoxGetAreaCbox);
} }
return sum; pi_destroyBox(box);
} return sum;
}

Figure 6-74: Comparing UsagelEfticiency of Two Procedural Interface Models

Sometimes the system itself will allocate an object dynamically and return it to the
client. In such cases, a handle class is usually provided by the underlying system to
manage the memory for that object. For example, consider a Shape interface that is a
protocol class for all kinds of Sha pe objects. Now suppose there is a class Poi nt Iter
that is also a protocol for a variety of specific iterator objects that sequence over some
collection of points. It is possible to ask an arbitrary Shap e through its protocol to
allocate a shape-specific iterator (derived from Poi ntIt e r) and return it by loading a
user-supplied instance of a Poi ntlterHandl e, as shown in Figure 6-75. 18

class Point;
class Pointlter {
·public:
II CREATORS
virtual ~Pointlter();

18 See also the Iterator design pattern in gamma, Chapter 5, pp. 257-71.
Section 6.5.4 Accessing and Manipulating Opaque Objects 439

II MANIPULATORS
virtual void reset() = 0;
virtual void operator++() = 0;
II ACCESSORS
virtual operator const void *() const = 0;
virtual const Point operator()() const = 0;
};
class PointIterHandle {
PointIter *d_iter_p;
PointlterHandle& operator=(PointIterHandle&);
PointIterHandle(PointIterHandle&);
public:
II CREATORS
PointlterHandle();
PointlterHandle(PointIter *iterator);
~PointlterHandle();

II MANIPULATORS
void loadIter(Pointlter *newDynamiclyAllocatedlterator);
II ACCESSORS
PointIter& operator()() const;
operator PointIter&() const;
PointIter *operator-)() const;
PointIter& operator*() canst;
};
class Shape {
I I ...
public:
I I ...
II ACCESSORS
virtual void getVertices(PointIterHandle *returnValue) - 0;
I I ...
};

Figure 6-75: Using Handles to Manage Dynamic Memory in·C++

In this example, the system is dynamically allocating an iterator object and placing it
in a user-supplied handle. Since the underlying system itself is allocating the memory,
the customer is not authorized to delete it. The customer is, however, authorized to
create and destroy an instance of a Poi ntIt e r Han d 1e. The customer therefore creates
a Poi ntlterHandl e and passes it to the getVerti ces function of Shape. The handle
is then loaded by the system with a dynamically allocated pointer to a Poi ntIt e r. The
customer uses the object contained in and managed by the handle. When the handle is
destroyed by the customer, the destructor of the handle in tum destroys the contained,
dynamically allocated iterator. Reusing a handle to obtain another iterator also
prompts the handle to destroy any previously installed iterator before loading the new
440 Insulation Chapter 6

one. An ANSI C-compatible procedural interface for the functionality of Figure 6-75
is given in Figure 6-76. The usage of such an interface is illustrated in Figure 6-77.

typedef struct Point Point; II ANSI C compatibility

typedef struct Pointlter Pointlter; II ANSI C compatibility
typedef struct PointIterHandle PointIterHandle; II ANSI C compatibility
typedef struct Shape Shape; II ANSI C compatibility

1***** PointIter *****1

1* MANIPULATORS *1
int pi_fPointIterIsValidCconst Pointlter *thisIter);
void pi_fPointlterGetltem(const PointIter *thisIter, Point *returnValue);

1* ACCESSORS *1
void pi_fPointIterResetCPointlter *thislter);
void pi_fPointlterAdvance(Pointlter *thisIter);

1***** PointlterHandle *****1

1* CREATORS *1
PointlterHa·ndle *pi_createPointlterHandleC);
void pi_destroyPointIterHandleCPointlterHandle *thisHandle);

1* MANIPULATORS *1
1* void pi_fPointlterHandleLoadlter(PointIterHandle *thisHandle,
* PointIter *newDynamicPointlter);
* Note: not necessary to expose this dangerous function
*1

1* ACCESSORS *1
Pointlter *pi_fPointlterHandleGetlterCconst PointlterHandle *thisHandle);
1* Note: for a procedural interface, this one accessor is sufficient *1

1***** Shape *****1

1* ACCESSORS *1
void pi_fShapeGetVerticesCShape *thisShape, PointIterHandle *returnValue);

Figure 6-76: An ANSI C-Compliant Procedural Interface Involving Handles

As a procedural-interface author for a large system, you may discover a class interface
that returns a dynamically allocated object directly, without placing it in a client-sup-
plied handle. In such cases, it will be necessary for you to find (or create) such a han-
dle of the appropriate type and require your clients to pass a non-con s t pointer to that
handle into your interface function. You will then have to load the handle with the
system-allocated object yourself. Doing so will preserve the principle that clients of
the procedural interface are authorized to delete only what they explicitly allocate.
Section 6.5.5 Inheritance and Opaque Objects 441

void f(Shape *shape)

{
PointlterHandle *handle = pi_createPointlterHandle();
Point *pt' = pi_createPoint();
Pointlter *it;

pi_fShapeGetVertices(shape, handle);
it = pi_fPointlterHandleGetlter(handle);

for (; pi_fPointlterIsValid(it); pi_fPointlterAdvance(it)) {

pi_fPointlterGetltem(it, pt);
/* do stuff with current pOint */
}

pi_destroyPoint(pt);
pi_destroyPointlterHandle(handle);
}

Figure 6-77: Using an ANSI C-Compliant Procedural Interface Involving Handles

6.5.5 Inheritance and Opaque Objects

Converting between types related by inheritance is yet another aspect of writing pro-
cedural interfaces for object-oriented designs that must be addressed. The issue at
hand involves how we present a type-safe, procedural interface that supports the
notion of pointer conversion implied by inheritance.

Figure 6-78: Examples of Inheritance Relationships

Consider the class diagram shown in Figure 6-78. Class B derives publicly from both
Al and A2, which means that all of the functionality of both Al and A2 is accessible
442 Insulation Chapter 6

through the public interface of B. Unfortunately, insulation prevents even C++ Cus-
tomers of a procedural interface from knowing anything about how types AI, A2, and
B are related. For example, if we have a pointer to an object of type B and we want to
call a member function defined in AI, we would be out of luck; this is obviously not
acceptable.

Our first thought might be to duplicate the functionality defined in both A1 and A2 in
B. Doing so creates a large number of redundant functions and solves only half the
problem. Suppose we want to use an object of type B in a function that takes an object
of type A1. Should we also make duplicates of each function for every combination of
derived types? I think not.

The C++ language supports implicit (standard) conversion from pointers of a given
type to pointers of another type when the first type publicly inherits (either directly or
indirectly) from the second; it will be necessary to make that conversion explicit in the
procedural interface.

Al *pi_convertBAl(B*);
A2 *pi_convertBA2(B*);
C *pi_convertDIC(Dl*);
C *pi_convertD2C(DC*):

const Al ~pi_convertConstBAl(const B*);

canst A2 *pi_convertConstBA2Cconst B*);
canst C *pi_convertConstDIC(const 01*);
canst C *pi_convertConstD2C(const 02*);

Figure 6-79: Examples of (Standard) Conversion Functions

The explicit conversion functions corresponding to Figure 6-78 are shown in Figure
6-79. In this example, four inheritance relationships induced eight functions. Notice
that there are two kinds of functions: one for canst objects and one for non-canst
objects. Although this seems painful, it gets even worse.
Section 6.5.5 Inheritance and Opaque Objects 443

C____A~l_) ( A2 )

new inheritance relationship

Figure 6·80: 'fransitivity of Conversions in Inheritance Hierarchy

Now consider what would happen if we introduced one more inheritance relationship
from C to B, as shown in Figure 6-80. In addition to the obvious two additional conver-
sion routines

B *pi_convertCBCC*);
canst B *pi_convertCanstCB(const C*);

the transitive nature of the IsA relation potentially introduces the following 16 conver-
sions as well:

B *pi_convertDIB(OI*);
Al *pi_convertDIAICDI*);
A2 *pi_canvertDIA2(D1*);
B *pi_convertD2B(D2*);
Al *pi_convert02Al(02*);
A2 *pi_canvert02A2(D2*);
Al *pi_convertCAl(C*);
A2 *pi_convertCA2(C*);
const B *pi_convertConst01BCcanst 01*);
canst Al *pi_canvertConstDlAl(const 01*):
const A2 *pi_convertConstOlA2(const D1*);
canst B *pi_canvertConstD2BCconst 02*);
canst Al *pi_canvertConst02AI(const 02*);
canst A2 *pi_convertConst02A2(const 02*);
canst Al *pi_convertConstCA1(const C*);
canst A2 *pi_convertCanstCA2(const C*);

Although it is not absolutely necessary to supply a function to provide direct conver-

sion from type 01 to type A2, users of the procedural interface may already be
444 Insulation Chapter 6

annoyed by having to use one conversion function-let alone three. There is clearly a
trade-off between the number of conversion-function definitions provided and the
number of conversion-function calls required at runtime.

Attempting to maintain and document all of these functions by hand is expensive and
error prone. Fortunately these conversion functions are trivial, regular, and easy to
generate accurately using techniques similar to those employed in Appendix C for
determining level numbers. Note that instead of trying to document all these conver-
sion functions, it is far more manageable to show users how to infer the appropriate
name based on the two type names:

<Type2> *pi_canvert<Typel><Type2>«Typel>*);

canst <Type2> *pi_convertConst<Typel><Type2>(canst <Typel>*);

To summarize: a procedural interface is entirely different from other insulation tech-

niques presented in this chapter, and it satisfies an entirely different set of objectives.
Techniques such as extracting a protocol and creating a wrapper layer serve both to
encapsulate as well as insulate clients from the low-level organization of a subsystem.
These other techniques enable the side-by-side reuse of low-level implementation
components without any possibility of breaching the encapsulation of subsystems that
use them internally.

By contrast, the primary purpose of a procedural interface is to insulate clients from

all organizational aspects below a certain level. There is usually no intention of allow-
ing customer reuse of the underlying objects-often for proprietary reasons. The main
advantage of this insulation technique is that it does not require the up-front design
effort that accompanies the provision of an encapsulating interface, nor does it impose
the overhead of additional objects to achieve the encapsulation. The issue of long-dis-
tance friendship is eliminated because the underlying types are publicly available in
name, but the header files that enable direct access to the functionality defined for
these types are universally withheld from customers.

Providing a procedural interface has the distinct disadvantage that, in its pure form,
clients lose the ability to extend the functionality of the system through the use of
inheritance. With careful design, however, it is possible to provide a procedural inter-
face and augment it with a few select header files to mitigate this problem. Procedural
interfaces require the use of long and tedious function names to do what is nonnally
section 6.6 To Insulate or Not to Insulate 445

done by members within class scope, operators, and standard conversions. Function
names become even more tedious when the interface is made ANSI C compliant.

A procedural interface is neither object oriented nor particularly elegant, but it does
have one big advantage: a procedural interface can always be used to insulate the
organization of a large system from clients-even if such an interface was not consid-
ered during the early stages of the design.

6.6 To Insulate or Not to Insulate

Frequent recompilation due to changing header files is something we would like to

avoid imposing on the clients of our components. Such "spontaneous" recompilations
during development are both annoying and expensive.

There is little we can do to insulate our ~lients from the changes we make to the logi-
cal interface of our components-a fact that underscores the importance of getting
major interfaces correct early in the design process. Batching up such changes and
publishing them infrequently in the form of a software release (see Section 7.6) can
reduce but not eliminate their cost.

As we have seen from the previous sections in this chapter, there are steps we can take
that will reduce or even eliminate our clients' recompilation costs due to changes in
the logical implementations of our components. But insulation itself is not without
cost. Sometimes it will take more development effort to create an insulating interface
for a component, and in some cases insulation could significantly degrade runtime
performance.

In the following subsections we discuss the costs of insulation, when insulation is (or
is not) appropriate, and what kinds of insulation techniques are best suited for particu-
lar situations that arise commonly in practice.

6.6.1 The Cost of Insulation

Insulating a class clearly can affect its runtime performance. The degree of impact
depends on the class itself, the way it is used, and the techniques used to insulate it.
446 Insulation Chapter 6

Although computer architectures and compilers vary, the following

rule of thumb may help guide system architects in deciding whether
and how to insulate at the early stages of a design.

Relative Cost
Access of Access Alone
By value via inline function 1
By pointer via inline function 2
Via non-inline, non-virtual function 10
Via virtual-function mechanism 20

Relative Cost
Creation of Allocation Alone
Automatic 1.5
Dynamic 100+

Figure 6-81 provides some hard numbers for the relative costs of various forms of
function calls and object instantiation. As the figure shows, the cost of accessing data
either directly or through an inline function is statistically identical. Using the
CFRONT 3.0 C++ Compiler on a SUN SPARC-2 workstation with no optimization, it
takes about 1/8 of a microsecond to access an integer data member (either directly or
via an inline function) and assign it to another integer variable (see Figure 6-81a, c).
Notice that it takes 60 percent longer on a SPARC-2 and twice as long qn a SPARC-20 to
accomplish this operation if the access must go through a pointer (b, d).19

struct A {
int d_d;
inline int i() canst;
int f() canst;
virtual int v() canst;
};

19 The operation becomes bound by memory-access time on the faster SPARe 20.
section 6.6.1 The Cost of Insulation 447

int A::i() canst { return d_d; }

int A: :f() canst { return d_d; }-
int A::v() canst { return d_d; }

main ()
{
A a, *p = &a;
int j;
II TIME IN MICROSECONDS
II SPARC-2 SPARC-20

J - a.d - d ,. II a. 0.124 0.040

J - p->d_d; II b. 0.200 0.080
j - a.i(); II c. 0.125 0.040
J - p->iC); II d. o. 199 0.080
J - a.f(); II e. 0.575 0.3.01
J - p-)f(); II ·f. 0.599 0.301
J - p->v(); II 9. 1.076 0.543

{ Aa } II h . 0.175 0.060
{ A *p = new A; delete p; } II i . 11.757 5.478
}

Figure 6-81: Some Relative Costs of Access and Creation

For a fully insulating class, there can be no inline functions, so eacb access of a pri-
vate member requires indirection through a pointer. The cost of accessing a data
member with a regular function instead of an inline function is increased by almost a
factor of four (e). Notice that the indirection now adds less than 5 percent to the total
cost of the operation (f). That is, the added access cost of not declaring a member
function i n1 i n e dominates the small additional overhead of the indirection.

For a protocol class, there can be no non-virtual functions, and the pointer indirection
is now mandatory. All function calls must go through the virtual function call mecha-
nism. The cost of performing this same operation with a dynamically bound function
instead of a statically bound function again doubles the cost of the operation (g).20
Although the virtual-function call mechanism is somewhat slower than a direct-func-
tion call, for tiny accessor functions it can be significantly slower than accessing the
data directly, using an inline function. Often, however, if one can afford to make a
function non-jnline, one can afford to make it virtual as well. Note that as the size of

20 It
is worth reiterating that the depth of an inheritance hierarchy does not affect the runtime perfor-
mance of virtual functions. Each class maintains its own virtual table(s), so the cost of dispatching
any virtual function is independent of the number of derivations in the class hierarchy.
448 Insulation Chapter 6

the function grows, the runtime cost associated with executing the body of the func-
tion will soon swamp the cost of whatever calling mechanism is used; the speed
improvement of inline over dynamically bound function calls will then become negligible.

A distinguishing property of a concrete class is that it can be instantiated. When an

object with a fully insulated implementation is created as an automatic variable (on
the program stack), its implementation structure must be allocated separately. As
shown at the bottom of Figure 6-81, the cost of dynamically allocating a struct (on
the heap) can be two orders of magnitude slower than automatic allocation (h, i). The
development effort in object-specific memory management -necessary to defray this
cost can be significant, and class-based management techniques can lead to undesir-
able side effects (see Section 10.3.4.2). Even worse, the cost of dynamic allocation
typically depends on the size of the application and specifically on the current utiliza-
tion/fragmentation of the particular runtime dynamic memory-management system.
For these reasons, full insulation for tiny, lightweight concrete classes may be con-
traindicated, especially for objects that are frequently created on the program stack or
returned by value from functions.

6.6.2 When Not to Insulate

Insulating clients from changes made to encapsulated implementation details of a com-

ponent in itself is good; however, not all component interfaces should be insulating.

The decision not to insulate the implementation of a component may

be based on the knowledge that the component is not widely used.

Some components are simply not intended for general use. When the audience of a
component is limited, insulation is no longer critical. In that case, the impact of
changes to the uninsulated implementation may not pose any great threat. In fact
some component may be specific to a subsystem that defines a few interface (wrap-
per) components that themselves completely insulate the entire multi-component sub-
system from general users. Examples are the p2p_router of Chapter 4 and the graph
wrapper of Section 6.4.3.1. Heroic efforts to insulate the implementations of each of
the individual components that make up such a subsystem would be misplaced.
section 6.6.2 When Not to Insulate 449

Unless performance is known not to be an issue, it may be wise to

avoid insulating the implementation of low-level classes with tiny
accessor functions that are used widely throughout the system.

There are two distinct ways to reduce the frequency of recompilation resulting from
changes to the implementation:

1. Insulate the implementation better.

2. Make changes to the implementation less frequently.

DEFINITION : Light-weight is a term whose meaning depends on the

context in which it is used:
• does not depend on (many) other components,
• is not expensive to construct/destruct,
• does not allocate additional dynamic memory, and
• makes effective use of inline functions to access/manipulate
embedded data.

For widely used components, it is especially undesirable that clients be forced to

recompile as a result of changes to encapsulated details. Yet, as we know, insulation is
not free of performance cost. Small, light-weight classes such as Poi nt, St a c k, Lis t,
and other well-defined concrete data structures in computer science are not good can-
didates for insulation, even though they are used widely throughout the entire system.
Insulating such classes would impose an across-the-board performance burden that,
for many, would be hard to justify. In fact, for classes such as these with tiny accessor
functions that are called repeatedly, the overhead of using indirection and non-inline
functions could make them an order of magnitude slower, as was demonstrated in
Section 6.6.1.
450 Insulation Chapter 6

When the runtime cost of work done in a given function call is large relative to the
cost of the call itself, insulation will not pose a significant performance problem.
Therefore, if a class is widely used and its member functions are large, the implemen-
tation of that class should be insulated, regardless of any supposed performance
requirements. On the other hand, highly reused, public components 21 with tiny acces-
sor functions should probably not be insulating unless performance is clearly not an
issue. These factors are summarized in Figure 6-82.

Performance Requirement

I II
high
(Don't Insulate!) • (Insulate! )
•
. • . • • • • • • • • • • • • • • • •
•
III • IV
low •
(Don't Insulate?) •
(Insulate! )
Io....-_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~ Member Function Size
small large

Figure 6-82: When to Insulate a Widely U~ed Component

Fortunately public, low-level classes are typically developed, tuned, and tested thor-
oughly early in the development process. After that, they are seldom if ever modified.
Such intentionally non-insulating, globally used classes become almost like funda-
mental types in the system. Classes such as Poi nt, St r i n g, and Lis t are often used
both internally and as a "medium of exchange" among the major subsystems. It is
understood by developers that these highly reused types are not likely to change.

Insulating lightweight, widely used objects commonly returned by

value can significantly degrade overall runtime performance.

21 The term public here implies a low-level component or interface that is used widely throughout an
entire system.
Section 6.6.2 When Not to Insulate 451

For a tiny object that does not allocate additional dynamic memory at construction,
the additional cost of returning a fully insulating version of that object by value could
be so severe as to affect the design of the interfaces that use it.

canst Paint pt(1,2);

Point getPointA() II return by value

{
return pt;
}

void getPointB(Point *returnValue) II return via parameter

{
*returnValue = pt;
}

Figure 6-83 illustrates the added runtime cost of partially and fully insulating a Poi n t
class with respect to returning a Poi nt by value from a non-inline function. Using the
original non-insulating Poi n t class implementation of Figure 5-59, it takes 1.52
microseconds on a.SPARe 2 for a call to the getPointA function to return a Poi nt by
value. Moving all of the function definitions out of line while leaving the data mem-
bers embedded in the class definition causes this time to more than double (3.39
microseconds). Fully insulating the class (implying dynamic allocation of the data)
causes the function call to take 10 times as long as it would have for the non-insulat-
ing implementation. For an ultra light-weight class such as Poi nt, the reduction in
runtime performance incurred by insulating its logical implementation is probably
unacceptable.

Return by Value Return via Parameter

Description of Point Class SPARe 2 SPARe 20 SPARC2 SPARe 20

Original Point Class 1.52 0.75 1.16 0.52

Without Inline Functions 3.39 1.67 1.23 0.71
Fully Insulating Version: 15.82 6.96 1.49 0.73
(function call time in microseconds)

Figure 6-83: The Cost of Returning a Fully Insulating Poi n t Object

Instead of returning an insulating Poi n t by value, we might be tempted to pass in a

previously constructed Poi n t object and assign to it just to avoid the overhead of the
452 Insulation Chapter 6

dynamic allocation associated with the construction of a temporary Poi nt object. In

that case, the cost of fully insulating Poi n t does not exceed 30 percent on either archi-
tecture. The cost of creating one reusable instance of Poi nt by the client can now be
amortized over many repeated calls to functions returning points via the parameter
list. This interface style is similar to the one proposed for procedural interfaces in Sec-
tion 6.5.4, and is discussed further in Section 9.1.8.

Other reasons not to insulate could result from a shortage of personnel. There may be
no compelling reason to insulate, and the incremental increase in development time
necessary to achieve the insulation may not be deemed cost-effective. Creating a
wrapper requires significant planning and effort; deadlines and a lack of experience
may prevent potentially wrappable subsystems from getting wrapped properly.

Insulation may be omitted because the added physical complexity of introducing yet
another component may be judged not to be worth the potential benefit that would be
gained through insulation. Both protocols and wrappers involve creating a separate
component to act as the interface. This separate physical entity contributes to the
overall complexity of the physical architecture.
.
Finally, insulation is an additional, independent constraint on the implementation of a
component or subsystem. Addressing this requirement leads to a somewhat more
complex implementation that may be harder for some to understand and marginally
more difficult to maintain than an uninsulated component or subsystem. For example,
fully insulating a class requires creating a separate structure in the . c file and remem-
bering to dynamically allocate and delete it during construction and destruction,
respectivel y.

Added initial development cost, increased component count, and increased complex-
ity are at least tenable reasons to resist unnecessary insulation. There are, however,
clear overall maintenance benefits to be gained from insulation. In the absence of
compelling reasons one way or the other, keep in mind that insulation is more eco-
nomically removed than installed late in the development process.

For large, widely used objects, insulate early and selectively remove
the insulation later if necessary.
section 6.6.3 How to Insulate 453

Once a system is complete and performance analysis proves that removing the insula-
tion from a few key components significantly improves the overall system perfor-
mance, at least the benefits of the insulation will have been realized throughout the
bulk of the development effort. Waiting until the end of a large project to determine
empirically which components can be insulating without significant loss in perfor-
mance sacrifices much of the initial maintenance b'enefit that insulation provides.

To summarize: insulating an interface can result in dynamically allocated memory,

extra indirections, non-inline or virtual-function calls, explicit management of
dynamically allocated objects, and additional translation units. The cost of insulating
an interface in terms of performance, development effort, or complexity will some-
times outweigh the benefits of the insulation. On the other hand, some components
are neither lightweight nor stable, and yet are available for general use throughout the
system. These large, high-level, volatile, and widely used objects are prime candidates
for' insulation.

6.6.3 How to Insulate

In practice, there are two main ways to insulate clients from the logical implementation
of a class:

1. Extract a protocol for that class.

2. Everything else:
• Use partial implementation techniques.
• Convert this to a fully insulating concrete class.
• Create an insulating wrapper for the class .
.- Create a procedural interface for the class.

Because a protocol defines a pure interface, clients of the protocol not only do not
depend on the implementation at compile time, but, unlike with other techniques, they
need not depend on any particular implementation at link time either.

Classes that already employ virtual functions are probable candidates for "perfect"
insulation by extracting a protocol class. These objects are already treated as base
classes, and they already incur the extra overhead of carrying around a pointer to a
virtual-function table in every instance of the class. More often than not, base' classes
with virtual functions are not intended to be instantiated. If a class either declares any
pure virtual functions or declares all of its constructors non-p ub 1 i c, the base class
454 Insulation Chapter 6

cannot be instantiated on the program stack by public clients. Therefore, the usage of
such classes will be left essentially unaffected by insulating them with a protocol.

For utility classes that act as modules (e.g., GeomUt i 1 in Figure 5-21), there is no need to
create an instance of the class in order to use its functionality. In that case, declaring all
member functions s tat i c and non - i n1 i ne, and moving any static member data to the . c
file (at file scope), obviates the overhead of instantiation and the virtual call mechanism.

For a "small" class with mostly non-trivial accessor functions such as a reasonable
Stri ng class, total insulation might be appropriate. Notice here that the implementa-
tion of even simple functions such as equality (==) and assignment (=) potentially
involves loops, additional dynamic allocation, or at minimum another non-inline
function call to strcmp or strcpy. Insulating the implementation of this class would
actually facilitate performance tuning by allowing different implementation strategies
(e.g., reference counting and caching length) to be profiled and evaluated in the con-
text of actual usage without having to recompile the entire system. Again, the insula-
tion could always be removed (if necessary) much later in the development process.

Large, high-level, instantiatable objects (e.g, a circuit siI?ulator or parser) that do not
make use of inheritance or virtual functions in their interface can usually be "fully
insulated" or "wrapped" with negligible impact on either size or runtime overhead.
Insulation is indicated for such objects, especially when the object is intended for
widespread, general use outside of the local software development group.

The p2p_Router shown in Figure 4-2 illustrates an ideal example of a fully insulating
wrapper. The router is not a module; an instance of the router must be created and
"programmed" before it can be used. The work required to construct an instance of a
p2p-"-Router is not trivial, nor is the work done by the addObstructi on function used
to program it. However, the time spent using the router is completely dominated by
work done in the lower levels of the router subsystem on each call to the fin d Pat h
function. The added runtime cost of insulating the router is thus completely negligible.

As a final example, consider how we might go about insulating (someone else's) class
Sol i d, whose header is shown in Figure 6-84. Sol i d is intended to be a common base class
for a variety of solids but is not itself instantiatable. This intent is corroborated by observing
that the constructors and assignment operator for the class are declared pro tee ted ·

II solid.h
#ifndef INCLUDED_SOLID
#define INCLUDED_SOLID
Section 6.6.3 How to Insulate 455

#ifndef INCLUDED_IOSTREAM
#include <iostream.h>
#define INCLUDED_IOSTREAM
1tendif
class Solid {
int d_color;
double d_scale;
double d_density;
ostream *d_errorStream_p;
protected:
II STATIC MEMBERS
static double distance(double xl, double y1. double x2. double y2);
II CREATORS
Solid(ostream *errorStream, double density. double scale = 1.0);
Solid(const Solid& solid);
II MANIPULATORS
Solid& operator=(const Solid& solid):
void setColor(int color) { d_color = color; }
II ACCESSORS
virtual double surfaceEquation(double x, double y, double z) - 0;
II Point(x.y.z) is on the surface when function returns
II approximately 0 (to within some small tolerance).
ostream& errore) { return *d_errorStream_p; }
double masse) const { return density() * volume(); }
public:
II CREATORS
virtual,....Solid();
II MANIPULATORS
virtual void setTemperature(int degrees) = 0;
II Changing the temperature may affect color, depending on the
II actual object.
void setScale(int scale) { d_scale = scale; }
II ACCESSORS
virtual double temperature() const = 0;
int scal~() { return d_scale; }
int color() const { return d_color; }
double density() const { return d_density; }
double volume() const;
double centerOfMassInX() const;
double centerOfMassInY() const;
double centerOfMassInZ() canst;
/ I ...
};

#endif
Figure 6-84: Base-Class So 1 ; d with Public and Protected Interface
456 Insulation Chapter 6

The scale attribute of a So 1 i d determines the relative size of the object. Users of
So 1 i d are permitted to access and modify its scale directly. The protected pure-virtual
sur fa c e Equa t ion function allows a derived class to program the unique behaVior
necessary to describe its own surface (parameterized by sea 1 e ( )) through an implicit
equation. For example, the surface of a sphere might be described as

double Sphere::surfaceEquation(double x. double y, double z)

{
return x * x + y * y + z * z - scale() * scale();
}

Non-virtual functions in the base class use the surface equation to compute, among
other things, the Sol i d's volume and center of mass in each spatial dimension. Making
the surfaceEquat i on function protected prevents direct access to surfaceEquati on
by the pUblic. 22

Since it is up to the derived object to define both the behavior of getting and setting
the temperature and how that affects the color of the specific object, the public t em-
perature and setTemperature functions of Sol id have been declared pure virtual.
(Notice that the internal representation of the temperature is already insulated from
clients of the base class.)

Since all objects have a color (encoded as an integer), a private integer data member
and a public inline accessor are provided in the base class. General clients of Sol i d
are not permitted to set the color of an instance directly. Rather, they are required to
adjust its temperature, which in tum may affect the color of the object. The set Color
manipulator function is therefore protected, so that only the derived object itself can
alter the color of this instance directly.

The public interface provides several accessor functions, some of which (such as
vol ume) do substantial numerical work when invoked. The protecteq interface pro-
vides derived-class authors with several helper functions such as setTemperature
that may prove useful in implementing required virtual functions.

Rather than exposing the 0 s t rea mpointer data member directly in the protected inter-
face, the protected function err 0 r is supplied to provide a convenient stream refer-

22 Thedesired effect could also have been achieved by making this virtual function private, but that
would have made the tasks of the derived-class developer less obvious.
Section 6.6.3 How to Insulate 457

ence for reporting errors (such as setting the temperature too low or too high). The
mass may play a role in determining the color, particularly for a very large, dense
Sol i d such a black hole. The protected member function mas s, which calculates the
mass using members supplied in the public interface, is provided for the convenience
of derived-class authors. Finally, dis tan c e is a function frequently used by derived-
class authors. Unlike the mass helper function, di stance does not depend on an
instance of any class and so is made a protected static member of class So 1 i d.

Clearly the original author of the Sol i d base class did not consider insulation an
important design criterion, as evidenced by the casual use of inline functions. Fortu-
nately we have several techniques available to improve the insulation of the imple-
mentation of So 1 i d. These insulation improvements fall into two basic categories:
total and partial.

As an exercise, let us first see what kinds of incremental improvements we can make
to the class So 1 i d:

#ifndef INCLUDED_IOSTREAM
#include <iostream.h>
#define INCLUDED IOSTREAM
#endif

Without needing to think much at all, we can convert the above to c 1 ass 0 s t rea m; to
eliminate unnecessary compile-time dependence on the i ost ream header and to avoid
the unnecessary creation at startup of a static dummy object in every translation unit
that includes sol i d. h (see Section 7.8.1.3).

protected:
static double distance(double xl. double ylt double x2, double y2);

Since dis tan c e is a static function, it does not depend on the Shap e instance data; it
can easily be moved to a separate utility component.

protected:
double masse) const { return density() * volume(); }

The calculation perfonned by ma s s () depends only on attributes that are accessible

directly from Sha pe's public interface. A modified, static version of the rna s s function
can be moved to a separate utility component.
458 Insulation Chapter 6

class ostream; II already changed from #include <iostream.h>

private:
ostream *d_errorStream_p;

protected:
ostream& errore) { return *d_errorStream_p; }

It may be possible that some derived So 1 i d objects can be set to any temperature
without error. The error stream function, err 0 r ( ), is just a convenience that some
derived-class authors may find useful. We could simply remove the
d_errorStream_p data member from the factored implementation (as we did with
Scri be in the shape subsystem of Figure 6-26) and let derived-class authors imple-
ment an error stream only if needed.

private:
int d_color:
double d_scale;
double d_density;

protected:
void setColor(int color) { d_color = color; }

public:
int scale() { return d_scale; }
int color() canst { return d_color; }
double density() canst { return d_density; }

If we assume that none of the inline functions of So 1 i d is called so frequently that it

creates a performance problem, we can convert all inline functions to non-inline func-
tions. Doing this will also enable us to collect all of the factored data into one s t ruct
defined in the . c file. A somewhat more insulating version of the Sol i d base class is
shown in Figure 6-85.

II solid.h
#ifndef INCLUDED_SOLID
#define INCLUDED_SOLID

c 1ass Sol i d_ i ; II insulated member data

class Solid {
Solid_i *d_this;

protected:
II CREATORS
Solid(double density, double scale - 1.0);
Salid(const Solid& solid);
section 6.6.3 How to Insulate 459

II MANIPULATORS
Solid& operator=(const Solid& solid);
void setColor(int color)

II ACCESSORS
virtual double surfaceEquation(double x, double y, double z) - 0;
II Point(x,y,z) is on the surface when function returns
II approximately 0 (to within some small tolerance).
public:
II CREATORS
virtual ~Solid();

II MANIPULATORS
virtual void setTemperature(int degrees) = 0;
II Changing the temperature may affect color, depending on the
II actual object.
void setScale(int scale);

II ACCESSORS
virtual double temperature() canst - 0;
int scale():'
int color();
double density() canst;
double volume() canst;
double centerOfMassInX() canst;
double centerOfMasslnY() canst;
double centerOfMasslnZ() canst;
I I ...
};

lIendif

Figure 6-85: Somewhat More Insulating Abstract Class Sol; d

At this point, to do any better we will have to use some form of total insulation tech-
nique. We cannot fully insulate the implementation of this class as it stands because of
the use of virtual functions .. Wrapping this class would preclude general users from
deriving new kinds of So 1 i d at will. Of the insulation techniques presented in this
chapter, extracting a protocol is by far the best alternative here.

As with the Ca r class shown in Figure 6-30, we are unable simply to remove all of the
protected functions and place them in a separate utility because of their intimate
interaction with the instance itself. That is, functions in the protected interface (e.g.,
setCol or) were supplied only to implement virtual functions (e.g., setTemperature)
defined in derived classes. At the same time, these protected functions depend
460 Insulation Chapter 6

directly on instance information (e.g., d_co lor) that is accessible by clients via pUblic
functions (e.g., color) defined in this base class. It is primarily because of the virtual
function dependency on intrinsic instance data that we are forced to extract a protocol
to achieve total insulation.

Figure 6-86 shows the result of extracting a protocol from either the original Sol i d or
the partially insulated version. Notice how extracting a protocol class always enables
us to avoid exposing the protected members of the base class .
•
II solid.h
#ifndef INCLUDED SOLID
#define INCLUDED SOLID

class Solid {.
public:
II CREATORS
virtual ~Solid();

II MANIPULATORS
virtual void setTemperature(int degrees) = 0;
Il'Changing the temperature may affect color. depending on the
II actual object.
virtual void setScale(int scale);

II ACCESSORS
virtual double temperature() canst - 0;
virtual int scale():
virtual int color();
virtual double density() canst;
virtual double volume() canst;
virtual double centerOfMassInX() canst;
virtual double centerOfMasslnY() canst;
virtual double centerOfMasslnZ() canst;
I I ...
};

#endif

Figure 6-86: Protocol Class So 1 i d

6.6.4 How Much to Insulate

While the implementation of p2p_Router presented in Chapter 4 is insulated, it is not

"fully insulated" (as defined in Section 6.4.2) because the wrapp~r class holds a
pointer to another class over which the component does not have sole and complete
control. We would not, for example, be able to add an insulated data member to the
Section 6.6.4 How Much to Insulate 461

p2p_Ro ute r class without disturbing the independently tested implementation com-
ponentp2p_Routerlmp.

Sometimes total insulation is no more expensive at runtime than par-

tial insulation.

In many cases this degree of insulation may be good enough. But if p2p_router
defines a very public interface, we can do better. A fully insulating p2p_router com-
ponent would (forward) declare its own implementation structure (e.g.,
p2p_Router_i). Then, in the p2p_router.c file, struct p2p_Router_i would be
defined with a single embedded member of type p2p_Router Imp:

II p2p_router.c
#include "p2p_router.h"
#include "p2p_routerimp.h"

struct p2p_Router_i {
p2p_Routerlmp d_imp;
};

//

Now adding a "private" data member to p2p_Router _i neither affects clients of

p2p_Router nor requires changes to p2p_RouterImp:

1/ p2p_router.c
#include "p2p_router.h"
#include "p2p_routerimp.h"

struct p2p_Router_i {
p2p_Routerlmp d_imp;
int d_moreData; // added fully insulated detail
};

// ...
In this case, doing it right requires just a bit more development effort, but achieves
total insulation without affecting runtime perfonnance at all.
462 Insulation Chapter 6

Sometimes the last 10 percent of the insulation is attained at the cost

of a tenfold increase in runtime.

Sometimes obtaining the last little bit of insulation can be very costly. Recall from
Section 6.4.3 that we opted not to insulate all of the 9 rap h component class com-
pletely. To do so would have caused a disproportionately high cost in terms of runtime
performance. To illustrate this principle, consider the four related implementations of
the graph subsystem we have seen in this and the previous chapters:

System I: Factored Objects. This subsystem corresponds to the factored

implementation of Section 5.9. In this architecture, the subsystem was
levelizable but clients had to know about and use lower-level components
in order to use the graph.

System II: Encapsulating Wrapper. This subsystem corresponds to the

encapsulating wrapper implementation of Section 5.10. In this architec-
ture, clients can do everything necessary from a single wrapper compo-
nent.

System III: Insulating Wrapper. This subsystem fully insulates the imple-
mentations of three of the five wrapper classes presented in Figure 6-53.
The remaining two classes, Nod e I d and Ed gel d, expose their respective
implementation class names, Gnode and Gedge, in their physical (but not
their logical) interfaces.

System IV: Fully Insulating Wrapper. This subsystem fully insulates the
implementations of all five of the wrapper classes presented in Figure 6-53.

System I favored runtime performance over encapsulation. Changes to low-level

interfaces could cause clients to have to rework their code. System II places a thin
encapsulating wrapper over the graph subsystem. Clients are logically independent
of, but not insulated from, changes to these low-level components, and could be
Section 6.6.4 How Much to Insulate 463

forced to recompile. System III transforms the encapsulating wrapper of System II

into an almost fully insulating wrapper. Changes to any of the underlying components
cannot affect clients of the wrapper at compile time; however, it is not possible to ar~d
private data to Nodeld (Edgeld) without affecting either Gnode (Gedge) or cl;.~nts.
System IV represents a fully insulating wrapper; arbitrary changes to any of the five
wrapper-class implementations affect neither clients nor the underlying implementa-
tion components.

To illustrate the runtime cost of these various graph architectures under a spectrum of
operating conditions, I created a small test program to run a series of experiments. In
this program, the graph subsystem is used to create the arbitrary graph structure
shown in Figure 6-87. In this graph, each edge happens to have a weight of 1, but the
particular edge values will not affect the experiment.

Figure 6-87 Arbitrary Graph Consisting of 15 Nodes, Each of Degree 3

After creating an instance of this graph, the program invokes a Nod e I t e r to iterate
over all 15 nodes in the graph, accumulating the values obtained by calling s urn on
each. The recursive function s urn explores the graph from a specified node to a speci-
fied depth, accumulating the weights of the edges it encounters along the way. Since
sum is exploring a binary tree, the runtime of sum is exponential with respect to the
depth to which it searches.

The source for the actual test program is provided in Figure 6-88. The first command-
line argument to the test driver indicates the depth to which s urn is to explore the
464 Insulation Chapter 6

graph. The second command-line argument specifies the number of times to repeat
the (identical) experiment; this second argument is used to obtain accurate time mea-
surements for an average iteration.

II graph.t.e
#include "graph.h"
#include "node.h"
#include "edge.h"
#include <iostream.h>
#include <stdlib.h>

double sum(const Nodeld& node, int depth)

{
double result = 0;
if (depth> 0) {
for (Edgelter it(node); it; ++it)
if (it().from() != node) {
continue;
}
result += it()-;weightC);
result += sum(it().toC), depth - 1);
}
}
return result;
}

main (int argc, char *argv[])

{
int depth = 1; int repeat = 1;
if (argc > 1) depth = atoi(argv[l]);
if (argc > 2) repeat = atoiCargv[2]);
cout « "GRAPH: depth - " « depth
«" repeat = " « repeat « endl;
double total;

for (int i = 0; i < rep eat; ++ i) {

Graph g;
Nodeld n = g.addNode("n");

Nodeld nO = g.addNode("nO");
Nodeld n1 = g.addNodeC"n1");
g.addEdge(n, nO, 1);
9 . addE d9 e ( n, nIt 1);
Section 6.6.4 How Much to Insulate 465

NodeId nOD = g.addNode("nOO");

Nodeld n01 = g.addNode("n01");
Nodeld n10 = g.addNode("nlO");
Nodeld nIl = g.addNode("nl1");
g.addEdgeCnO, nOO, 1);
g.addEdgeCnO, nOl, 1);
g.addEdgeCnl, nl0, 1);
g.addEdgeCnl, nIl, 1);

Nodeld nOOO = g.addNodeC"nOOO");

Nodeld nOOI = g.addNodeC"nOOlfl);
Nodeld nOlO = g.addNode("nOIO");
Nodeld nOll = g.addNode("nOll");
Nodeld nIOO = g.addNode("n100");
Nodeld n101 = g.addNodeC"n10l");
Nodeld n1l0 = g.addNodeC"n1l0");
Nodeld nlI1 = g.addNode("nIll");
g.addEdgeCnOO, nOOO, 1);
g.addEdgeCnOO, nODI, 1);
g.addEdge(nOl, nOlO, 1);
g.addEdgeCnOl, nOll. 1);
g.addEdge(nlO, nIOO, I);
g.addEdge(n10, nI01, 1);
g.addEdgeCn11, n110, 1);
g.addEdgeCnll, nIll, 1);
g.addEdge(nOOO, n, I};
g.addEdgeCn001, n, 1);
g.addEdge(nOIO, n, 1);
g.addEdge(nOll. n, 1);
g.addEdge(nlOO. n, 1);
g.addEdge(nI01, n. 1);
g.addEdge(n110, n, 1);
g.addEdge(nl11, n, 1);
g.addEdge(nOOO, n, 1);
g.addEdgeCn001. n, 1);
g.addEdge(nOIO, n, 1);
g.addEdgeCnOl1, n, 1):
g.addEdge(nIOO, n, 1);
g.addEdge(nl0l, n, 1);
g.addEdge(nl10, n, 1);
g.addEdgeCn1Il, n, 1);

total = 0:
for CNodelter it(g); it; ++it) {
total += sum(itC), depth);
}
}

cout « "total - " « total « endl;

}

Figure 6-88: Test Driver for Measuring Runtime Efficiency of Graph Subsystems
466 Insulation Chapter 6

Running Time on SUN SPARe 20 (in CPU Seconds)

Mostly Fully
Factored Encapsulating Insulating Insulating
(Original) Wrapper Wrapper Wrapper
Depth System I System II System III System IV
0 0.0018 0.0018 0.0020 0.0033
(100%) (100%) (111 %) (183%)

1 0.0019 0.0020 0.0026 0.0115

2 0.0022 0.0024 0.0050 0.0381
3 0.0026 0.0031 0.0086 0.0675
4 0.0033 0.0043 0.0144 0.1023
5 0.0046 0.0063 0.0248 0.1438
(100%) (137%) (539%) (3,126%)

6 0.009 0.014 0.063 0.334

7 0.016 0.025 0.120 0.609
8 0.027 0.044 0.213 1.054
9 0.048 0.078 0.380 1.836
10 0.121 . 0.202 0.998 4.895
(100%) (167%) (825%) (4,045%)

11 0.23 0.38 1.91 9.37

12 0.41 0.68 3.40 16.42
13 0.74 1.22 6.06 28.94
14 1.92 3.22 15.95 77.87
15 3.69 6.15 30.51 148.44
(100%) (167%) (827%) (4,023%)

16 6.6 10.9 54.4 262.2

17 11.8 19.4 97.0 462.4
18 30.7 51.5 255.1 1245.5
19 58.9 98.5 488.1 2374.4
20 105.8 175.2 870.6 4194.8
(100%) (166%) (823%) (3,965%)

Figure 6-89: Runtime Cost of Various Graph System Architectures

Section 6.6.4 How Much to Insulate 467

The test driver was run for depths ranging from 0 to 20 with a repeat value of 1,000
(depth 0-5),100 (depth 6-10),10 (depth 11-15), and 1 (depth 16-20) on each of the
four systems described above. 23 The results of this very illuminating experiment are
given in Figure 6-89.

When the depth of the graph traversal is specified as 0, no graph traversal takes place.
Most of the time is spent in building up and tearing down the graph structure. These
kinds of operations are inherently relatively expensive; as the first line of Figure 6-89
indicates, the effects of encapsulating and even insulating are negligible and small,
respectively. When fully insulating, we incur a runtime cost that is 83 percent higher
th~n our cost when not insulating. This is because of the very pronounced increase in
the cost of returning a fully insulating Nodeld by value from Nodelter.

As we increase the depth of the graph, the cost of traversing it begins to affect overall
performance. Functions that are used to read the information in a graph are much
smaller and do much less work per call than those used to construct the graph. These
lightweight functions, however, are called many, many times in the course of travers-
ing the graph.

At a depth of 5, it takes 2.5 times as long for the experiment to run on System I as it
took at a depth of 0; however, many times that number of additional function calls are
occurring. If these small functions are made disproportionately expensive, the run-
time performance will suffer. At this same depth, the encapsulated System II now
experiences an increase of 37 percent compared to the runtime for the unwrapped
System I. The partial insulation of System III causes the experiment to take 5 times as
long. The dynamic allocations brought on by totally insulating Nodeld and Edgeld in
System VI have cost us a factor of 30!

At a depth of 10, it takes 100 times as long for the experiment to run on System I as it
did at a depth of O. The time spent calling those "little" functions now dominates the
runtime cost. For an encapsulating wrapper (System II), this experiment will run
about 67 percent longer. For an insulating wrapper (System III) it will take over 8
times as long, and for a fully insulating wrapper (System IV), it will take fully 40
times as long.

23 The test driver was trivially altered to accommodate the slightly different interface of System I.
468 Insulation Chapter 6

By scanning down Figure 6-89 from this point, we can see that we have reached the
other asymptote; increasing the depth does not further spread the respective runtime
performance ratios of these graph subsystem variants.

What lessons can be learned from this experiment?

1. Insulating the implementation of an object whose functions already do a

substantial amount of work below the insulating layer will have no
noticeable effect on runtime performance (suggesting that the level of
insulation is appropriate).

2. Encapsulating a subsystem with a wrapper whose functions do a non-triv-

ial amount of work below the encapsulating layer will have a negligible
effect on runtime performance (suggesting that the level of encapsulation
is appropriate).

3. Providing even an encapsulating wrapper for lightweight functions that

are called frequently can have a significant effect on overall performance
(perhaps suggesting that the level of encapsulation should be escalated).

4. Providing an insulating wrapper for lightweight functions that are called

frequently can have an overwhelming effect on overall performance
(forcing the level of insulation to be escalated).

5. Providing a totally insulating wrapper for tiny objects that are frequently
returned by value can have a devastating effect on overall performance
(forcing the degree of insulation to be reduced and/or the level of insula-
tion to be escalated).

6.7 Summary

In this chapter, we introduced the concept of insulation as the physical analog of the
logical concept commonly referred to as encapsulation. An implementation detail of a
component is insulated if it can be changed without forcing clients of the component
to recompile.

Several constructs were identified that could potentially result in undesirable compi1e~
time coupling:
Section 6.7 Summary 469

• Inheritance and Layering force the definitions of the inherited or embed-

ded object to be seen by the client.

• Inline Functions and Private Members expose the implementation details

of this object to clients.

• Protected Members expose the protected details to public clients.

• Compiler-Generated Functions force an implementation change to affect

the declared interface.

• Include Directives artificially create compile-time coupling.

• Default Arguments expose the default value to clients.

• Enumerations cause unnecessary compile-time coupling due to improper

placement and/or inappropriate reuse.

All other things being equal, it is better to insulate a particular implementation detail
from a client than not-even if other details remain uninsulated. Partial implementa-
tion techniques are used to reduce the extent of compile-time coupling without incur-
ring all of the overhead that total insulation could imply:

• Removing private inheritance by converting WasA to HoldsA.

• Removing embedded data members by converting HasA to HoldsA.

• Removing private member functions by making them static at file scope

and moving them to the . c file.

• Removing protected member functions by creating a separate utility

component and/or extracting a protocol.

• Removing private member data by extracting a protocol and/or moving

static data to the . c file at file scope.

• Removing compiler-generated functions by explicitly defining these

functions.
470 Insulation Chapter 6

• Removing include directives by removing unnecessary include directives

or replacing them with (forward) class declarations.

• Removing default arguments by replacing valid default values with invalid

default values or employing multiple function declarations.

• Removing enumerations by relocating them to the . c file, replacing them

with con s t static class member data, or redistributing them among the
classes that use them.

For widely used interfaces, avoiding all compile-time dependency on the underlying
implementation details is highly desirable. Three general insulation approaches were
discussed to insulate clients from all implementation details:

• Protocol Class: Creating an abstract "protocol" class is a general insulation

technique for factoring the interface and implementation of an abstract
base class. Not only are clients insulated from changes to the implemen-
tation at compile time, but even link-time dependency on a specific
implementation is eliminated.

• Fully Insulating Concrete Class: A "fully insulating" concrete class holds

a single opaque pointer to a private structure defined entirely in the . c
file. This s t rue t contains all of the implementation details that were for-
merly in the private section of the original class.

• Insulating Wrapper Component: The concept of an encapsulating wrapper

component (from Chapter 5) can be extended to a fully insulating wrap-
per component. Wrappers are typically used to insulate several other
components or even an entire subsystem. Unlike a procedural interface, a
wrapper layer requires considerable up-front planning and top-down
design. In particular, care must be taken in the design of a multi-compo-
nent wrapper to avoid the need for long-distance friendships.

A procedural inteiface is a collection of functions that sit on top of an existing collec-

tion of components and expose a subset of the functionality to ~nd users. A procedural
interface is an alternative to total insulation. Unlike the three total insulation tech-
niques presented in this chapter, a procedural interface is neither logically encapsulat-
ing nor entirely insulating. A procedural interface does have the unique advantage of
section 6.7 Summary 471

working on very large systems that may not have been designed with a procedural
interface in mind.

Generally if a component is used widely throughout a system, its interface should be

insulating; however, not all interfaces should be insulating. For example, insulation
may not be practical, particularly for lightweight, reusable components. Common rea-
sons for choosing not to insulate a component include the following:

• Exposure: The number of clients may be known to be small.

• Time to access data: The class may have embedded data and make effective
use of tiny inline functions to access it.

• Time to create objects: A tiny class (e.g., Poi nt) may not already allocate
dynamic memory.

• (Initial) development cost: There may be no compelling reason to insulate;

the extra development effort may not be cost-effective.

• Number of components: Insulation may require yet another component (e.g.,

to hold a protocol or wrapper), increasing maintenance costs.

• Component complexity: An insulated implementation (e.g., a "fully

insulated" s t rue t defined in the . c file) may be harder to understand
and maintain than an uninsulated implementation.
 Packages

A large project can span many developers, several layers of management, and even
multiple geographic sites. The physical structure of the system will reflect not only
the logical structure of the application but' also the organizational structure of the
development team that implements it. Large systems require hierarchical physical
organization beyond what can be accomplished by a levelizable hierarchy of individ-
ual components alone. In order to encompass more complex functionality, we need to
introduce a unit of physical design at a higher level of abstraction. This chapter
addresses the physical structure needed to support the development of very large sys-
tems. In particular, we introduce a macro unit of physical design referred to in this
book as a package.

A package aggregates a collection of related components into a logically cohesive

physical unit. Each package has an associated registered prefix that immediately iden-
tifies both files and file-scope logical constructs as belonging to that package. After
presenting the semantics and physical structure of packages in the first two sections,
we apply the concept of levelization at the package level in Section 7.3. Here we dis-
cover that many of the techniques that applied at the component level also work when
applied to entire packages. At the same time, new issues that must be addressed sepa-
rately emerge. In Section 7.4, we explore the concept of insulation at the package
level, in terms of improving the usability of complex subsystems for clients. Then, in
Section 7.5, we extend the envelope of project size by hierarchically grouping pack-
ages. In Section 7.6, we discuss the process of releasing a stable snapshot of a system.
One possible directory structure for releasing a large system is presented. We then
examine a technique known as patching for updating published software between

473
474 Packages Chapter,

releases. Next, in Section 7.7, we examine the role of rna i n () in an object-oriented

software system, along with the special privileges and responsibilities of owning the
"top" of a program. Finally, in Section 7.8, we examine the first few moments in the
life of a program's execution. It is at this time that potentially all file-scoped static
data is initialized.

In large systems, static initialization can lead to unacceptably long invocation times.
We take a look at four alternative initialization strategies, comparing their relative
strengths and weaknesses as we go. We also address the need to clean up before pro-
gram exit in order to facilitate memory regression testing.

7.1 From Components to Packages

In Chapter 3 we introduced the component as the smallest unit of physical design. A

typical component contains one, two, or even several classes, often accompanied by
appropriate free operators. Normally a component consists of many hundreds of lines
of C++ source code and comments, with the . hand . c files often of comparable
length. Occasionally a low-level definition component will have fewer than a hundred
lines and an empty . c file. Sometimes wrapper components for large subsystems or
machine-generated components will be measured in the thousands of lines. As a rule
of thumb, however, several hundred to a thousand lines is a good practical size for
components in terms of effective comprehension, testing, and reuse.

As we saw with the p2p_router example in Chapter 4, we can build fairly complex
subsystems using only a handful of components. In that example, the implementation
of high-level functionality declared within a single component interface was distrib-
uted across a hierarchy of components that greatly improved its testability. A system
consisting of tens of thousands of lines can be supported easily without further parti-
tioning. But what if our systems are much bigger than this? Suppose they consist of
hundreds of thousands of lines of code. How would we address the physical organiza-
tion of literally hundreds of components? As ever, we will address complexity with
the tried-and-true: abstraction and hierarchy.

When designing a system from the highest level, there are almost always large pieces
that it makes sense to talk about abstractly as individual units. Consider the design of an
interpreter for a large language (such as C++) shown in Figure 7-1. Each of the sub-
systems described in that design is likely to be too large and complex to fit appropriately
Section 7.1 From Components to Packages 475

into a single component. These larger units (indicated in Figure 7-1 with a double
box) are each implemented as a collection of levelizable components.

Interpreter

Parser Evaluator Formatter

Runtime Database

Figure 7.. 1: High-Level Interpreter Architecture

The dependencies in Figure 7-1 between these larger units represent an envelope for
the aggregate dependencies among the components that comprise each subsystem.
For example, the runtime database is an independent subsystem; it has no dependen-
cies on any external components. Each of the parser, evaluator, and formatter sub-
systems has components that depend on one or more components in the runtime
database, but none of the components in any of these three subsystems depends on
any components in the other two parallel subsystems. The top-level interpreter con-
sists of components that depend on components within each of the three parallel sub-
systems (and perhaps directly on components within the runtime database). Carefully
partitioning a system into large units and then considering the aggregate dependencies
among these units is critical when distributing the development effort for projects
across multiple individuals, development teams, or geographical sites.

Although the design of Figure 7-1 would not be considered a large project, it could eas-
ily be assigned to more than one developer. There is a natural partitioning that would
allow several developers to work on this project concurrently. After the runtime data-
base is designed, there would be an opportunity for three concurrent development
efforts to begin on the parsing, evaluating, and formatting functionality. Once these
pieces start to fall into place, the implementation and testing of the top-level inter-
preter can begin.
476 Packages Chapter 7

Until now, we have discussed these separate subsystems as conceptual units with no
actual physical partitions. If the entire project is expected to require only 20,000 lines
of code and is being implemented by a single developer, there may be no compelling
need to partition the overall architecture into distinct physical units. However, if the
design is, say, 80,000 lines of code or if more than one developer will be working on
the project at any given time, there is a much greater need for the conceptual physical
partitioning to become concrete.

DEFINITION: Apackage is a collection of components organized as

a physically cohesive unit.

The tenn package refers to a generally acyclic, often hierarchical collection of com-
ponents that together have a cohesive semantic purpose. Physically, a package con-
sists of a collection of header files along with a single library file containing the
information in the corresponding object (. 0) files. A package might consist of a
loosely coupled collection of low-level, reusable components, such as the original
Standard Components library from AT&T, 1 and now the new Standard Template
Library (STL) developed at Hewlett-Packard. 2 A package might also consist of a spe-
cial-purpose subsystem intended for use by only a single client, such as the
p2p_router subsystem from Chapter 4.

Figure 7-2 illustrates one possible organization for packages within a file system. In
this organization, all packages exist at the same level in the directory structure regard-
less of their physical interdependencies. All headers (required outside a given pack-
age) are placed in a single, system-wide directory called i ncl ude. A library file
corresponding to each package is placed in a single systemwide directory called 1i b•
.
Each package directory contains files holding the source code for components aSSOCI-
ated with that package. As illustrated schematically in Figure 7-2, package pk contains
n components: pk_cl, pk_c2, ... , pk_cn in its source directory. Each component
(e.g., p k_c i) has an associated header' file (p k_c i . h), an implementation file
(p k_ c i . c), and an individual test driver (p k_ c i . t . c) that can be used to exercise the
functionality implemented in the component inc~ementally. Note that to be effective,

1 stroostrup94, Section 8.3, pp. 184-185.

2 STL has been accepted as part of the ANSIJISO (Draft) C++ Standard (see musser).
section 7.1 From Components to Packages 477

these hierarchical test drivers should be considered as much a part of the system
source code as the components they test. These drivers can be easily distinguished
from the implementation files by their . t . c. suffix.

system

develop include 1i b
pl_cl. h libpl.a
. . . libp2.a
pl_cn.h . . .
p2_cl.h libpm.a
. . ..
.. . .
pm_ cn.h

pI p2 pm

dependencies exported

source
pk_cI.h pk_ cl.c pk_cl.t.c
pk_c2.h pk_c2.c pk_c2.t.c
. . . . . . . . .
pk_ci .h pk_ci .c pk_ci .t.c
.. . . .. • . . . .
pk_cn.h pk_cn.c pk_cn.t.c

Figure 7-2: A Simple Development Organization for Packages

In addition to the source directory, there are two files under each package directory.
The dependenci es file holds the names of all other packages upon which this pack-
age is authorized to depend. That is, in order to use this package, clients will not have
to include or link to any other component defined in another package unless that pack-
age is named in the dependencies file associated with this package. Although package
dependencies seldom change, it does occasionally happen. Specifying these depen-
dencies is the job of the system architect; verifying them is a process that can and
should be automated.
478 Packages Chapter 7

The ex p0 r ted file contains a list of component headers that are to be placed in the
systemwide include directory of Figure 7-2 for use by general clients. Since not- all
headers defined in a package are intended for use by external clients, the set of
exported headers may be a proper subset of the components defined within the package.

Placing headers used outside a package in a single systemwide include directory

makes it convenient to specify where to look for exported header files. Exporting only
the subset of headers needed by other packages reduces the clutter through which cli-
ents must wade in order to use the product. Placing these headers in a single directory
can also improve a client's compile-time efficiency with respect to looking in multiple
package directories (see Section 7.6.1). Placing library files in a single directory simply
makes using them more convenient.

Until now, we have addressed levelization only at the component level. Recall from
Section 4.7 that components that do not depend on any other (local) components are
assigned a level of 1. By local we were referring to components defined in our pack-
age; components defined in other packages were assigned a level of o.

Level 2:

Package Level 2:

Levell:

pkgb

I/"',"}']"I
Package Level I:

I;I;:j~~,~:",;l[l I;ijti:~ir~~~ 1;1.1

pkga
Figure 7-3: Dependencies on Components in Other Packages

Figure 7-3 illustrates the way we have all along been treating the dependencies of ~ur
subsystem (pkgb) on another subsystem (pkga). When testing our own pack age hlef-
section 7.1 From Components to Packages 479

archically, we assume that components defined outside our package are already tested
and known to be internally correct. We therefore can assign to each of these external
components a level number of 0 with respect to our local components. Components
within our own package (e.g., i and j) that do not depend on any other components
local to this package are defined to have a level of 1. Components that depend locally
on components at level 1 but no higher (e.g., k and 1) are at level 2.

DEFINI~ION: A package x DependsOn another package y if one or

more components in x DependsOn one or more components in y.

Just as relationships between logical constructs defined within components imply

physical dependencies (see Section 3.4), dependencies among packages are implied
by the individual dependencies among the components that comprise them. In Figure
7-3, for example, component i in pkgb DependsOn component a in pkga and compo-
nent 1 in pkgb DependsOn components 9 and h in package pkga. Therefore according
to the definition, pkgb DependsOn pkga. Provided pkga does not depend back on
p kgb, we can assign level numbers to these packages as a whole, just as we did for the
individual components within a package.

Packages provide a powerful mechanism of abstraction for developers and architects

alike. Figure 7-4a shows a collection of 20 components, a through t, grouped into
four packages: pkga, pkgb, pkgc, and pkgd. Each package defines a high-level archi-
tectural unit consisting of a cohesive hierarchy of cooperating components, united for
a common purpose.

In contrast, Figure 7-4b shows the identical system represented as an unpackaged,

levelizable collection of individual components. The modularity and the abstraction
of the high-level architecture are gone; we have lost the semantic value attached to
these high-level partitions created during the process of the top-down design.

As Figure 7-4a shows, the individual component dependencies across package bound-
aries of Figure 7-4b have been abstracted away and replaced with overall package
dependencies. For example, the dependencies of component p on component d and
component q on components e and f shown in Figure 7-4b are collectively repre-
sented in Figure 7-4a by the package dependency of pkgc on pkga.
480 Packages Chapter 7

Lev 2:
Package Level 3:
Lev 1:

pkgd

Lev 2: Lev 4:

Package Level 2:
Lev 1:

pkgb
Lev 3:

Lev 2:
--
Lev 1:

pkgc

Lev 2:
Package Levell:
Lev 1:
~:.2.:.:..........:......l

pkga

(a) Top-Down Decomposition of a System into Packages of Components

Section 7.1 From Components to Packages 481

Component Level 6:

Component Level 5:

Component Level 4:

Component Level 3:

Component Level 2:

Component Levell:

(b) Equivalent Unpackaged System

Figure 7-4: 1\vo Different Views of a System

Notice that the local component level numbers within each package of Figure 7-4a
still begin with level 1. This is again because dependencies on other packages are
treated as "primary inputs" (see Section 4.7) and, for the purposes of hierarchical test-
ing, are presumed to be correct. As is common, each of these packages contains leaf
components (i.e., components such as t that do not depend on any other components
in the system). In an unpackaged system (Figure 7-4b), these leaf components would
all have an absolute component level of 1. Consequently there is a tendency for many
components to fall to the lower levels of the unpackaged diagram, perhaps obscuring
their purpose. It is by packaging these leaf components along with their clients that
we are able to improve the modularity of the system.

Often a package will hold dozens of components. While a typical component might
consist of 500 to 1,000 lines of source code, a typical package might encompass any-
where from 5,000 to 50,000 lines of source. Decomposing large designs into cohesive
packages of manageable size greatly simplifies the development process. For develop-
ers, comprehending up to a few dozen components and their detailed interdependen-
482 Pac~ages Chapter 7

cies within a package (as in Figure 7-4a) is significantly easier than understanding the
arbitrary dependencies among potentially hundreds of unpackaged components (as in
Figure 7-4b).

Packaging also allows system architects to understand, discuss, and develop the Over-
all architecture of a large system at a much higher level of abstraction than would oth-
erwise be possible. For example, an architect can delineate the responsibility of a
package and then specify acceptable dependencies among entire packages as part of
the overall system design without having to address individual components. The
actual package dependencies can later be extracted from the source code and com-
pared against the architect's specification.

Having all the packages at the same level in the directory structure makes them easily
accessible to developers. Using special-purpose tools (see Appendix C), the physical
package interdependencies can be extracted from and compared against the architect's
specification located within the dependencies file of the development structure shown
in Figure 7-2. Note that to guarantee package-Ievellevelization when testing a new
version of a package, only those packages named in the dependencies file should have
their exported headers made available for inclusion or their libraries files supplied in
the link command.

The partitioning of components into packages is governed by more than just some
arbitrary threshold of size or complexity. Identifying package-sized units of cohesive
functionality is a natural consequence of top-down design. As with class dependen-
cies within a single component, component dependencies within a package are often
more numerous and intricate than dependencies across package boundaries. Because
of their more localized nature, the physical character of dependencies among compo-
nents within a package often involves more compile-time coupling than their inter-
package counterparts. In fact, some components defined in a package may be merely
insulated implementation details of other components defined in the same package;
the headers for these implementation components would probably not be made avail-
able outside of the package.

Packaging also reflects the development organization. Typically, a package will be

owned/authored by a single developer. The impact of change within a package can be
well understood by its owner and dealt with both consistently and effectivelY·
Changes across package boundaries affect other developers and perhaps even the
section 7.2 Registered Package Prefixes 483

entire system. Therefore, highly coupled parts of the system are often better off being
part of a single package.

The degree to which parts of the system are likely to be reused as a unit also plays a
role in the packaging of components. In the example of Figure 7-1, the runtime data-
base may be used by a suite of tools, while the three parallel subsystems are used only
once. Even if the runtime database were very small in comparison to these other parts
of the system, it could make sense to place this low-level subsystem in its own pack-
age to avoid tying its reusable functionality to any of the other less-often-used pack-
ages. (An analogous argument was presented for demoting enum E in Section 5.3;
Figures 5-24 and 5-25.)

To summarize: a package is an aggregate unit of physical design. Like a component, a

package serves as a cohesive unit of related functionality fulfilling a common pur-
pose. Packages serve as both abstractions for architects and partitions for developers.
-Package composition is determined by several factors, including semantic cohesion,
the nature of physical dependencies, the organization of the development team, and
the potential for independent reuse.

7.2 Registered Package Prefixes

As was discussed in Section 2.3.5, the only logical entities declared at file scope in
header files are classes, structs, unions, and free operators. The reason given for this
restriction was to reduce the opportunity for name collisions. When only a single
developer is involved, ,it is not hard to avoid name collisions simply by following this
strategy. N amespaces (as discussed in Section 7.2.2) can be used to counter a disorga-
nized proliferation of global names resulting from the integration ,of completely inde-
pendent development efforts. However, when dealing with many developers working
across multiple sites on a large unified system, a more structured approach is required.

7.2.1 The Need for Prefixes

The approach taken here, which ensures unique global class names, requires that each
package be associated with a unique registered prefix consisting of two to five charac-
ters. When a package is first created, its prefix is registered with some company-wide
authority or service so that no other package developer will inadvertently reuse it.
Each construct in the header file declared at file scope is prepended with the package
484 Packages Chapter 7

prefix. The . c and . h files implementing this component are also each prepended
with the same prefix. It is by prepending each global name with this registered prefix
that we are able to guarantee that similar names defined in distinct packages cannot
possibly collide.

Major Desigll Rule

Prepend every global identifier with its package prefix.

For example, a package of geometric primitives would consist of a number of inde-

pendent reusable components. A component defining a basic point would not be
named poi nt but would instead be named geom_po; nt, where "geom" is the unique
registered prefix associated with the geom package. The class defining a geometric
point would not be called Poi nt but instead would be called geom_Poi nt. 3

Each identifier declared at file scope must be preceded by a registered prefix in order
to ensure the avoidance of name conflicts across package boundaries. Although only
classes, structs, unions, and free operators are allowed at file scope, extraordinary cir-
cumstances (such as the ANSI C--compliant interface of Section 6.5.4) could force an
exception to this rule. If for some reason we were to declare a function, variable, enu-
meration, or typedef at file scope in a header file, we would still want to make sure to
prepend each of its file-scope identifiers with the appropriate package prefix. This
independent design rule is illustrated in Figure 7-5.

3 Note that for the purposes of the convention for distinguishing type names from non-type names as
presented in Section 2.7, we have elected not to treat the prefix as part of the identifier. An equiva-
lent and equally valid convention would be to capitalize the prefix instead (e.g., Geom_poi nt). Capi-
talizing Poi nt rather than Geom merely emphasizes that geom_Poi nt is a Poi nt type in the geom
package.
Section 7.2.1 The Need for Prefixes 485

II geom_polygon.h II Filenames are always all lowercase.

#ifndef GEOM_POLYGON II CPP macros are always all uppercase.
#define GEOM_POLYGON II Hence, the prefix must be case insensitive.
enum geom_Color { geom_REO, geom_GREEN, geom_BLUE };
II Proscribed global enumeration must still use package prefixes.
typedef short int geoffi_Int16;
II Proscribed global typedefs must still use package prefixes.
class geom_Polygon {
II Global class definitions are not a design rule violation.
};

int operator==(const geom_Polygon& left, const geom_Polygon& right);

II Global operators are not a design rule violation.
geom_area();
II Proscribed global functions must still use package prefixes.
double geom_scaleFactor;
II Proscribed global variables must still use package prefixes.
/lendif

Figure 7-5: Even Proscribed Constructs at File Scope Require Prefixes

Identifiers declared within class scope need not have package prefixes because the
enclosing class (which is prefixed) provides a natural shield against collisions as well
as a suitable grouping for related functionality. Similarly, identifiers with internal
linkage, declared and used entirely within a single . c file, also need not use prefixes.
That is, the scope of a typedef, enumeration, static variable, or static (or inline) free
function specified within a . c file is limited to a single translation unit and therefore
cannot collide with an identical short name defined locally within another translation
unit. Static class member data and non-inline member functions have external link-
age. It is therefore appropriate to use package prefixes for class names even when the
class itself is defined and used entirely within a single . c file. Otherwise we run the
risk that such a hidden class will produce external symbols that at link time might col-
lide with those of a class hidden in the . c file of a component belonging to some other
package. 4

4 Note that prefixes are not strictly necessary for hidden classes, provided that the developer ensures
that all aspects of linkage for the hidden class are internal. A generally useful extension to the pack-
age-prefix technique for naming classes with external linkage that are private to a component was
presented in the context of fully insulating classes at the end of Section 6.4.2.
486 Packages Chapter 7

Major Desigll Rule

Prepend every source file name with its package prefix.

Names generated by the compiler are sometimes geared to the name of the source file
itself. In CFRONT, file names are used as a basis for naming both the virtual tables and
also for naming the entry points for initializing and destroying instances of user-
defined types defined at file scope-both of which have external linkage. Therefore,
to avoid link-time conflicts, it is important that all source files in the system have
unique names. The library containing all of the .0 files for the geom package would
also be adorned in some manner with the "geom" prefix (e.g., 1 i bgeom. a on a Unix
system).

For many systems, harsh limitations on file-name length make prepending unique pre-
fixes painful. If the limitation is eight characters or fewer, the file names could get
rather cryptic. On some systems (e.g., Unix), file-name length is not a problem except
for archaic constraints placed on the length of the name of a . a file that can be placed
in a library archive file. The names of the corresponding . c files may need to be con-
strained to some relatively small length (as low as 14 characters on some Unix-based
systems). In this case we can either make the. h files correspondingly short to match
the . c file, or we can provide some sort of external cross reference to allow longer
header file names to be associated with shorter (abbreviated) implementation file
names. On my Unix system I use symbolic links to achieve this mapping during
development.

7.2.2 Namespaces

In July of 1993, the ANSIIISO Committee adopted the namespace construct designed
by Bjarne Stroustrup to aid in resolving collisions between global identifiers with the
same name. 5 For example,

5 stroustrup94, Section 17.1, p. 400.

Section 7.2.2 Namespaces 487

namespace geom {
class Point { /* ... *1 };
Point& operator==(const Point& left, const Point& right);
class Polygon { /* ... */ };
// ...
}

defines a namespace geom. The constructs declared within the braces are placed within
their own scope and therefore will not collide with either global names or names
declared in any other namespace. While using directives are supplied primarily to ease
transition, the intent is always to use explicit qualifications via using-declarations: 6

void mySpace::Class::f()
{
9e om: : Poi nt p ( 3 , 2 ) ;
// ...
}

As you can see, both namespaces and registered prefixes can be used in similar ways
to avoid name conflicts among classes developed within a single company. Neither,
however, can serve as a complete substitute for the other.

When dealing with C++ application libraries supplied from two distinct vendors,
there are several potential problems. As described in Appendix B, if the compilers
used to develop these libraries are not compatible, you're out of luck. But even if you
can get both vendors to supply compatible libraries (architecture, operating system,
and compilerllinker), there is no central authority with which to register prefixes; thus
there is a distinct possibility that globally defined names will collide. Herein lies the
power of the namespace construct.

Placing all library code developed by a company within a single namespace wrapper
makes it impossible to ensure that even the unlikely event of matching both prefixes
and identifiers can be overcome merely by explicit qualification. Suppose two compa-
nies, SDL and SCI, both supply geometric library software. Each company decides to
create a "unique" package prefix called geom. Obviously, there is a possibility that one
or more of the geometric names (e.g., Poi nt, Line, Po 1ygon) within those packages
will coincide.

-
6stroustrup94, Sections 17.4.2, p. 408 and 17.4.5.3, p. 414.
488 Packages Chapter 7

II sdl/geom_point.h
#ifndef INCLUDED_SDL_GEOM_POINT
#define INCLUDED_SDL_GEOM_POINT
namespace SOL {

class geom_Point {
I I ...
public:
geom_Point(int x. int y);
geom_PointCconst geom_Paint& pOint);
----geom_Po;nt();
geom_Point& operator=Cconst geom_Point& point);
void setX(int x);
void setY(int y);
int xC) const;
int y() const;
};

int operator==(const geom_Point& left, const geom_Point& right);

int operator!=(const geom_Paint& left, const geom_Point& right);

}
II sci/geom_point.h
itendif #ifndef INCLUDED_GEOM_POINT
#define INCLUDED_GEOM_POINT

class geom_Point { 1* ... *1 }

int operator==(const geom_Point& left,

const geom_Point& right):
int operator!=(const geom_Point& left,
canst geom_Point& right);

I!endif
II my_class.c
#include "my_class.hl!
#include <sdl/geom_point.h>
#include <sci/geom_point.h>

v0 i d my _C 1 ass: : f C) {
SDL::geom_Po;nt p(1,2);
::geom_Point qC3,4);
I I ...
}

Figure 7-6: Using Namespaces to Resolve Name Conflicts Among Vendors

section 7.2.2 N amespaces 489

If one (or both) of these companies has the foresight to place their code within a single
companywide namespace, the identifier name conflict-resolution problems disappear.7

The technique of combining package prefixes and namespaces to resolve name con-
flicts among multiple vendors is illustrated in Figure 7-6. Even though SCI did not
choose to use namespaces, we can still access their geom_Poi nt class by prepending
the scope resolution operator (: :) to designate true file scope. Notice that SDL has
protected itself, but SCI is at risk if some other vendor or one of its clients did not
choose to take these precautions.

Because the C++ language supports the arbitrary nesting of namespaces,8 we could
have elected to resolve interpackage name collisions within our company by replacing
package prefixes with package namespaces. For example,

void f
{
SDL::geom_Point pt; II package prefix
// ...
}

would instead be written

void f
{
SDL::geom::Point pt; 1/ package namespace
// ...
}

As we will soon see, however, replacing package prefixes with package namespaces is
ill advised.

As of the writing of this book (May 1996), the namespace feature of the C++ language
was not generally available. Even if it were, it would not affect the need for prefixes,
which have many advantages beyond ~imply avoiding name collisions. A package
serves a cohesive purpose that unites the components within it. Each package tends to
take on its own character. This phenomenon is due in part to the intrinsic nature of the
package and also to the subtle variations in style promulgated by its author. By identi-
fying a component or class as belonging to a particular package, you immediately

7 We could still have problems if compiler-generated symbols with extemallinkage are generated
based on the file name (as is the case in some implementations).
8 strollstrup94, Section 17.4.5.4, pp. 415-416.
490 Packages Chapter 7

provide a context that aids in understanding its broader purpose. 9 In time, the package
prefix will be the first thing to catch your eye when reading application code that
depends on components from mUltiple packages.

The dominant purpose of a prefix is to identify uniquely the physical

package in which the component or class is defined.

In addition to its semantic cohesion, a package is also a physical unit. An important

function of a package prefix is to identify where in the file system the definition of a
given class or component can be found. Package prefixes also make searching for
"use" of a particular package much easier. There are many other trivial advantages to
package prefixes. For example, if you forget to link-in a particular package, the nature
of the problem will be immediately obvious, as illustrated in Figure 7-7.

john@john: CC -g geom_iter.o geom_util.o geom_file.o geom_print.o \

-0 a.out -L/home/sys/lib -lxref -lne -llst -lcrx
ld: Undefined symbol
___ ct __ lOstdc_ErrorFCQ2_10stdc_Error8errorNumPCciT2
stdc_AssocList: :operator=(const stdc_AssocList&)
stdc_AssocList: :ope~ator+=(const stdc_AssocList&)
stdc_AssocList: :operator+=(const stdc_NameValue&)
stdc_AssocList::setAssociation(const stdc_NameValue&)
stdc_Plcontext: :pop() canst
stdc_Plcontext::push() const
operator==(const stdc_AssocList&,const stdc_AssocList&)
stdc_AssocListlter: :operatorC)() const
stdc_Error::operator=(const stdc_Error&)
stdc_Plcontext::~stdc_Plcontext()
operator«(ostream&,const stdc_Error&)
stdc_AssocList::~stdc_AssocList()
vtbl 14stdc_AssocList
stdc_Error::~stdc_Error()
Compilation failed
john@john:

Figure 7-7: Link-Time Errors Resulting from Missing the stdc Package Library

9 Forthis and other views on segmenting the global namespace, see stroustrup94, Sections 17.4.1,
p. 406; and 17.4.5.5, pp. 416-417.
section 7.2.3' Preserving Prefix Integrity 491

Much more important, a package, like a component, represents a cohesive unit. As

with component-level design, the logical and physical design of a package are tightly
interleaved. It is important when discussing packages and, in particular, their physical
interdependencies, that the logical and physical properties of each package coincide.

7.2.3 Preserving Prefix Integrity

The purpose of a prefix is to provide a hierarchical identification for the physicalloca-

tion of the definition of a component or global logical construct. For well-designed
packages with cohesive functionality, the package prefix contributes semantic as well as
physical information. Using the prefix to identify only semantic properties defeats its
primary purpose of forcing similarly prefixed cohesive logical functionality to be pack-
aged together in the same physical library.

Ideally, a package prefix will connote cohesive logical and organiza-

tional characteristics in addition to denoting the physical library in
which a component or class is defined.

Sometimes there may be a great temptation to distribute logically related units across
mUltiple physical libraries and to assign these logical units a common package prefix.
For example, a given package (pub) might provide a set of low-level, reusable con-
tainer types. Each of these components and each of the types defined therein would
begin with, the prefix p u b_o Now suppose we are developing our own application
package (x r 2e) and discover we need a new type, Bt r e e, which happens to have similar
characteristics (low level, container, reusable) to those found in the pub package.
What should we do?

We might be tempted to call this component pub_btree and place it in our own
library to reflect its logical relationship to the pub package. This urge should be sup-
pressed. The fact that all components with a given package prefix reside in a single
physical library is too valuable to both understanding and managing the organization
of large systems to be sacrificed.
492 Packages Chapter 7

Instead we have two viable alternatives-each with its own advantages:

1. Call it xr2e_Btree and place it in our own package.

2. Call it pub_Btree and place it in the pub package.

Probably the easier thing to do is simply to call the class x r 2e_B t r e e and define it in a
component that is part of our own package. Implementing this object locally reduces
the likelihood that it will be reused-which can be both good and bad. By defining the
Btree within the same package, we retain ownership and therefore need not be as con-
cerned about making changes or enhancements to it should it suit our needs to do so.

The potential for reuse is not always obvious a priori. It may be that we believe that no
one else will need a Bt ree type, so we'll just write it and keep it for ourselves. If oth-
ers think this way and the btree component turns out to be truly reusable, we may
eventually see several redundant versions of a Bt r e e popping up in our system. As a
rule, if we see three or more comparable versions of a bt ree component in our system,
the component may very well be a good candidate for reuse. At this point, we should
probably evaluate the impact of consolidating our system by moving a single, unified
version of Btree to the more public pub package (and changing its prefix to pub_).

Often, we will believe that a component is reusable only to find that it is not needed
by others. Placing such deadweight in highly reusable packages is worse than delay-
ing the entry of potentially reusable components into the pub package. It is almost
always easier to make functionality more rather than less public. If in doubt, it is bet-
ter to defer adding a component to a widely used package until empirical evidence
warrants it.

If we are convinced at the outset that a component absolutely belongs in another pack-
age, then we will need to talk to the developer responsible for maintaining that pack-
age. If your proposal is compelling, as it might well be for a Bt ree, the owner of pub
may agree to write the btree component for you and place it in the pub package for
all to use. Note that you will now be just another customer of the pub package, and
give up the right to add intrusive special customizations to the pub_btree component.

Scheduling constraints may force you to write the component yourself and hand it
over (along with its incremental test driver) to the pub package developer. After a
careful review, this developer will assume ownership, and again you will become just
like any other client with no special privileges.
Section 7.3 Package Levelizalion 493

The important trade-off here is that if you create a component redundantly, then you
can make it exactly what you want it to be. You will not have to negotiate with other
package developers, and you may be able to avoid additional package dependencies.
If you hand this component over to some other package developer, you relinquish
responsibility for and control over its functionality_ If the component is not inherently
reusable, the cost to you and to others of sharing it will probably outweigh any bene-
fit. If the component is a good candidate for reuse, then it could be in everyone's best
interest to have it defined and maintained in a single, semantically cohesive, lower-
level package where it can be found and reused easily.

While the notion of a translation unit is well defined in the C++ language, the notion
of a package is entirely the work of the system developers, and its implementation is
dependent on the particular operating system. Because packages are not part of the
language, it is up to system architects and developers to create these cohesive parti-
tions within a large system, almost entirely on their own.

Computer-aided software engineering (CASE) tools such as browsers help to uncover

many detailed properties and interdependencies among a large collection of classes.
Good tools are an important part of the design process, but they are not a substitute for
the thoughtful partitioning of semantically cohesive functionality into distinct physi-
cal units. Even the fanciest runtime environment would be hard pressed to convey as
quickly the same semantic information afforded by consistently tagging logically
cohesive global constructs with their physical package prefix.

The registered prefix convention for all global identifiers and files is admittedly pain-
ful at first. In time, most people not only adjust to it but come to depend on it during
their daily development efforts. The advantages afforded by registered package pre-
fixes are well worth the extra effort for developing very large projects.

7.3 Package Levelization

By analogy, a component is to its package as a planet is to its solar system. Each com-
ponent describes a 'physical entity, and each package describes a cohesive aggregate
of these physical entities. The ·physical coupling. among the nearby components
within a package is typically more acute than the coupling between components in
distinct packages.
494 PackageS Chapter 7

7.3.1 The Importance of Levelizing Packages

As yoU recall, avoiding cyclic dependencies among individual components was an

importallt design goal because it aided in incremental comprehension, testing, and reuse.

l\rlajor Desigll Rule

Avoid cyclic .dependencies among packages.

Avoiding cyclic dependencies among packages is a major design rule for the follow-
ing reaSons:

1. Development. When linking the entire system or any portion thereof, it

will be necessary to specify the order in which package libraries are
called upon to resolve undefined symbols. If the envelope of dependen-
cies among components within in"ividual packages is acyclic, there will
be at least one order that will be guaranteed to resolve all symbols during
linking. In Unix, cyclic dependencies among packages imply that it will
be necessary to include J one or more libraries at least twice in the link
command. Doing so increases the time necessary to link a subsystem by
forcing one or more libraries to be searched multiple times. Worse, minor
changes to the calling sequence of functions could cause the library order
required by the link command to change, thus causing the link to fail. It
then becomes a non-trivial exercise to determine a new library linking
sequence that does not result in undefined symbols.

2. Marketing. Often a system will have a basic functionality and several

optional add-on packages of functionality, as is illustrated in Figure 7-8.
If the system itself depends on anyone of these add-on packages, then
that add-on is not optional and must be shipped with the system. If any of
the add-on packages are mutually dependent, they cannot be marketed
and sold as truly independent options.
Section 7.3.1 The Importance of Levelizing Packages 495

Add-On 1 Add-On 2 Add-On 3

Core System

Figure 7-8: Acyclic Package Dependencies Provide Flexibility

3. Usability. Even if marketing is not an issue, users will not want to have to
link-in a huge library or several large libraries just to use some simple func-
tionality of the basic system (or just one of the supposedly independent
applications). Minimizing package interdependencies reduces the number
of libraries that must be linked into an application, which can in turn help to
reduce the ultimate size of the executable image (both in core and on disk).

4. Production. To support concurrent development in very large systems, it

is effective to have a staged release process (as discussed in Section 7.6).
Acyclic hierarchies of packages are collected into even larger architec-
tural units called groups. Group levelization is then used to partition these
groups into layers, which are then released in levelized order from bot-
tom to top. Allowing cyclic dependencies among packages would impede
our ability to form groups and therefore to make staged releases.

5. Reliability. Design for testability dictates that there be a way to test a large
system incrementally and hierarchically_ Avoiding cyclic dependencies
among the macroscopic parts of the system is merely a natural conse-
quence of this paradigm.
496 Packages Chapter,

Although we might be serene enough to tolerate cyclic dependencies among a few com-
ponents within a single package due to carelessness, ignorance, or special circumstance,
we must be steadfast in our resolve to avoid cyclic dependencies among packages.

7.3.2 Package Levelization Techinques

The techniques for avoiding cyclic dependencies among packages are similar to those
for avoiding cyclic dependencies among components. The basic goal is to ensure that,
if the components in package b depend on services supplied by components in pack-
age a, then components in package a do not depend either directly or indirectly on
components in package b.

r2d2 c3po

Figure 7-9: Two Mutually Dependent Packages

Figure 7-9 illustrates a situation in which two packages, r2d2 and c3po, have become
interdependent. This problem is entirely analogous to the problem we encountered in
Figure 5-3, where logical constructs in both rectangl e and wi ndow caused a mutual
dependency between these two components.

mS

r2d2 c3po

Figure 7-10: Escalating Mutual Dependencies Between Packages

section 7.3.2 Package Levelization Techinques 497

Fortunately, remedies analogous to those given in Section 5.2 for untangling the
rectangl e and wi ndow component dependencies apply here also. For example, we
could escalate two of the components contributing to mutual package-level depen-
dency to a higher package level, as shown in Figure 7 -10. Or we might decide to apply
the more general repackaging technique shown in Figure 5-36 to come up with two
entirely new packages.

It is not necessarily possible to assign a single package prefix to the

subset of components used directly by clients of a multi-package
subsystem.

The purpose of a package is to unite closely related collections of components into

modular physical entities that can be referred to abstractly and reused effectively. Fig-
ure 7-11 shows a hierarchy of components whose dependencies form a binary tree.
Clearly these components are levelizable. As discussed in Section 7.2.3, however, all
components with the same package prefix should belong to the same physical library.
Consequently, the packages implied by these prefixes are not levelizable, as, illustrated
in Figure 7-12.

Component Level 3:

Component Level 2:

Component Levell: ,', '•,'.'i··'··'·"··"·."'.comp4-

Figure 7-11: Implied Cyclic Package Dependencies

The problem identified by Figure 7-12 can arise in practice when a single prefix is
assigned to a conceptual presentation package-that is, a package containing every-
thing directly usable by clients of a multi-package subsystem. If this presentation pack-
age defines both protocol classes (which are inherently very low level) and wrapper
498 Packages Chapter,

components (which are inherently very high level), it will not be possible to interleave
components from separate, intermediate-level implementation packages and maintain
a levelizable package hierarchy. The solution to this common problem is simply to pro-
vide two separate packages for presentation to clients. One package will reside at the
bottom of the package hierarchy and contain components that define only protocol
classes; the second will reside at the top of the subsystem and define only wrappers.

priv

pub

Figure 7-12: Levelizable Component Hierarchy; Unlevelizable Package Hierarchy

7.3.3 Partitioning a System

Although ensuring levelizability among packages is essential, that alone is not suffi-
cient. For example, Figure 7 -13a illustrates a bottom-up approach to packaging in
which we have merely taken the unpackaged design of Figure 7-13b and carefully
diced it into packages whose aggregate dependencies on other packages form an acy-
clic graph. But simply partitioning a sea of levelizable components into an otherwise
arbitrary set of levelizable packages does not address an important aspect of design:
cohesion. To be effective, a package should consist of components and logical entities
that have related semantic characteristics, tight coupling, or otherwise make sense to
be packaged together and treated abstractly at a higher level.
Section 7.3.3 Partitioning a System 499

* y

x ·W *Redundant Edge

(a) Abstract Package-Level Dependency Diagram

I package z I
I I
I I
I I
I

I package y
package X
I I
I I
I
I - --
I
--
I I
I I
I .. .. .. ..'.'. IIII~ I
I ·······f . . .
IL ______ ~
package w
___________ ~
II ______ ~

(b) Detailed Package/Component Dependency Diagram

Figure 7-13: Less Useful, Physically P~rtitioned System (Compare with Figure 7-4)
500 Packages Chapter,

When adding a new component to a package, both the logical and

physical characteristics of the component should be considered.

As discussed in terms of subsystems in Section 5.7, dependency is also a factor that

should be considered when incorporating components into packages. Suppose a given
package is lightweight in character, depending on no other packages. Suppose further
that adding a single, logically cohesive component would force clients of that package
to link with ten other packages. Even if the logical cohesion of the component is ideal
for the package, the impact of the additional dependencies would probably override
any other consideration. Both logical and organizational cohesion should be consid-
ered as defining the character of a package.

A better solution in this case would be to create a separate package for this new com-
ponent, with a similar, perhaps, but not identical prefix that conveys the similar nature
of the logical semantics yet distinguishes the physical dependency implications. By
placing this heavyweight component in a separate package, clients of the light-weight
package will not be saddled with the overhead of unwanted and oppressive dependencies
on libraries they do not need.

7.3.4 Multi-Site Development

The geographical distribution of the development team coupled with interpackage

dependencies will influence how package ownership is distributed among developers.
Consider the system of packages described in Figure 7 -14. Suppose our company has
two geographically separate development sites, Nand S. How should we distribute
the workload across these two separate sites?
section 7.3.4 Multi-Site Development 501

ed sym

elem I· cmp

prim

geom pub grph

Figure 7-14: System of Packages and Their Physical Dependencies

Logistically, it makes sense that the package dependencies across sites be minimized
to whatever extent is possible in order to reduce inefficiencies associated with inter-
site communication. Consider the package development distributions proposed in Fig-
ure 7-15. Distribution (A) is pathologically bad, with seven direct package
dependencies across sites. Dividing the diagram with a vertical line (B) illustrates
another inappropriate partition with five direct intersite dependencies. Dividing the
diagram with a horizontal line (C) may provide an optimal solution with a cost of only
three long-distance direct dependencies. Both (D) and (E) also provide potentially
optimal solutions if the complexity of packages and/or available resources at each site
are not evenly distributed.
502 Packages Chapter 7

I (B)
I
·. ·.•· . . r.· . .·. .·•. ·····<·······.·············. . .·. . . ·. . ·•..·. . . i
4
r::=::::::::::::=::::::::::::::, I.. .. . . . . . . . .

I . (lJ) sy m
L----- _ ------ll

I
I
I
-1-
(C)

(A)

geom
__ .J

N S N S N S N S N S
pub geom geom grph geom elem geom cmp pub geom
.
pub
.
prIm pub cmp pub ed grph elm
grph pnm
.
elem ed elem cmp grph ed grph sym pnm cmp
. . ed
cmp sym ed sym pnm sym pnm
elem sym

(A) cost = 7 (B) cost = 5 (C) cost = 3 (D) cost = 3 (E) cost =3

Figure 7-15: Potential Package Development Assignments Across Sites

section 7.4 Package Insulation 503

Identifying packages and delineating their interdependencies can affect the success of
larger projects. Minimizing the cost of interpackage dependencies should be at the
forefront of every architect's mind throughout the design process. Most important,
avoiding the high cost of cyclic dependencies among packages is essential if the flex-
ibility and maintainability of the system are to be preserved.

To summarize: partitioning a system into a levelizable collection of packages is criti-

cal to the success of a large project. Most of the techniques discussed in Chapter 5 for
achieving a levelizable collection of components apply equally well to packages.
Apart from the coupling brought about by long-distance friendships, the same reason-
ing that enabled us to reduce CCD can be used to reduce the cost of interpackage
dependencies. Whenever we can take advantage of these techniques to reduce pack-
age interdependencies, we are making significant improvements toward the flexibility
and maintainability of the overall system.

7.4 Package Insulation

Packages present a higher level of abstraction than components. For packages with a
horizontal dependency structure, such as geom (see Section 4.13), we must export
most of the individual component header files in order to make the package function-
ality usable by clients (see Figure 7-16a). Even though placing these physically inde-
pendent components in a single package does not hide any additional details, we can
still benefit from the ability to refer to the aggregate of these components abstractly as
geom-a benefit that should not be underestimated.

Minimizing the number and size of exported header tiles enhances

usability.
504 Packages Chapter 7

Exported Headers Exported Headers

geom_a.h geom_b.h p2p_9.h
geom_c.h geom_d.h
geom_e.h geom_f.h Logical and Physical Abstraction
geom_9.h

Logical Abstraction Only

geom p2p
(a) Horizontal geom Package (b) Tree-Like p 2P Package

Figure 7-16: A Package Is a Logical and Potentially a Physical Abstraction

In the case of tree-like packages, such as p2p, that sport a small number of insulating
wrapper components, we can gain not only the conceptual abstraction but also a phys-
ical abstraction as well. It is by not exposing superfluous information in the form of
unnecessarily exported header files, as illustrated in Figure 7 -16b, that this physical
form of abstraction is realized.

As with a good component interface, the fewer details we expose in the interface of a
package, the easier it is for the package developer to maintain and tune its implemen-
tation. Minimizing the size of the physical interface to which the client is exposed can
also improve usability. Although the surface area of a horizontal package is inherently
large, this need not be the case for a tree-like package.

A package implementing a complex, application-specific subsystem, such as p2p, typ-

ically represents a substantial amount of functionality. The implementation of the sub-
system may span dozens of components. In order for clients to use this package, a
non-empty subset of the components must have their header files exported (i.e., made
available to components defined outside this package). Although package developers
and test engineers will always have access to all headers, regular clients of a package
need not necessarily be exposed to headers whose use is encapsulated.
section 7.4 Package Insulation 505

Answering "yes" to any of the following questions for a particular component defined
in a given package implies that the header for that component must be exported:

1. Do clients of this package need access to this component in order to use

any part of the functionality provided by this package as a whole?

2. Does any other exported component in this package fail to insulate its clients
from this components definition?

3. Do other packages need access to this component, (e.g., to reuse its func-
tionality independently in their own implementations)?

Consider a package such as p2p that is implemented hierarchically and presents its pub-
lic functionality entirely through the interface of only a small collection (one in this
case) of wrapper components. These wrapper components must be exported to the glo-
bal include directory (see Figure 7-2) in order for external clients to use the package.
However, there may be no need to export the header files of the remaining components.

Notice that we are not proposing to withhold header files here for the purpose of
encapsulating details, but rather as a means of reducing the clutter that clients must
wade through in order to use our package. Whether or not we export the implementa-
tion component header files depends on whether or not they are needed (or useful) for
I

purposes other than creating the. 0 files that belong to this package's library.

If a wrapper component is encapsulating but not insulating (see Section 6.4.3) it may
be necessary for the client's compiler to have seen the definition of one or more of its
implementation components in order to compile the wrapper interface. If so, you will
be forced to export implementation headers, your clients will depend on them at com-
pile time, and your flexibility to make changes to them will be impeded.

Finally, in the process of implementing our package, we may have accidentally created
one or more implementation components that other developers find useful in imple-
menting their own packages. In that case, we may generously decide to publish the
header files for these components. In doing so we enable reuse, but also enable addi-
tional interpackage coupling. This coupling could potentially have an adverse effect on
our ability to maintain our own package, and could introduce new package-level depen-
dencies that were not authorized by the system architect. Such additional package-level
dependencies would further constrain the levelizability of the entire system.
506 Packages Chapter 7

If a component header is not exported, our clients remain entirely insulated from it.
We may feel free to make any changes to it that we like. Once a header file is
exported, changes we make to its interface potentially affect many others who are
attempting to reuse its functionality. Even if we preserve the functionality, making
any change whatsoever to an exported component's header file will annoyingly force
clients who include this header to recompile. This example illustrates yet another situ-
ation in which reuse may not necessarily be a good thing.

In practice, there are likely to be a few low-level (horizontal) packages that export a
relatively large number of logically related and probably widely used component
headers. Most of the remaining packages would then implement sophisticated func-
tionality that operates on common, low-level types. Ideally these higher-level pack-
ages would export relatively small, high-level interfaces in the form of insulating
wrapper component headers.

7.5 Package Groups

In very large systems (involving many hundreds of thousands of lines of c++ code),
even a package is not at a high enough level of abstraction to be useful in discussing
overall system architecture. During the process of top-down design, architects will
identify major portions of the system. Each of these major subsystems will be imple-
mented by a team of developers; each subsystem will consist of a cohesive collection
of packages called a group.

DEFINITION: A package group is a collection of packages organized

as a physically cohesive unit.

Just as related components were collected into packages, so are related packages col-
lected into groups. An individual package is appropriately owned and maintained pri-
marily by a single developer, but a package group is usually owned by the project
manager (or principal engineer) of the development team that is charged with its
implementation.

The same principles that applied to the composition of individual 'packages and the
interdependencies among them (such as logical cohesion and avoiding cyclic depen-
dencies) apply to package groups as a whole. Like packages, groups should carry a
section 7.5 Package Groups 507

well-defined architectural significance that governs what is (and what is not) appro-
priate to belong to that group. For example, if a group is entitled "core functionality,"
we should resist placing packages that are not true to that label within this group.

DEFINITION: A package group 9 DependsOn another package

group h if one or more packages in 9 DependsOn one or more
packages in h.

Consider the large system shown in Figure 7-17. Although this system will consist of
some 40 packages (500,000 lines) when complete, its functionality naturally divides into
five vertically arranged package groups. Each of these groups consists of several pack-
ages. Not only are these packages individually levelizable, but the dependencies among
entire groups as defined above are also acyclic. That is, groups at higher levels contain
packages that depend on packages in groups at lower levels, but never vice versa.

Group LevelS: Graphical Editor

II II
ed
~
Group Level 4: Command-Line Interpreter
II II
cm ~ ..

Group Level 3: Application-Level Tool Kits

I I
tlk
~
Group Level 2: Core Database Functionality
II II
db
~
Group Levell: Reusable System-Independent Libraries

base
Figure 7-17: A Large-System Architecture
508 Packages Chapter 7

Package Level 3: dbi

Package Level 2: dba I dbb I I dbc I I dbd I dbe

Package Levell: dbt

Figure 7-18: Package Organization of Core Database Group

There are good reasons for wanting to merge individual package libraries into a single
large group library. Many of these reasons are analogous to those for merging the . 0
files of components into a single package library. Consider the internal, package-level
organization for the core database group shown in Figure 7 -18. In this architecture,
there are several packages used in the implementation of the core database functionality.

At the lowest level of the core database group, the dbt package represents a horizontal
collection of types and protocols used throughout the group and by its clients. At the
next level are a set of five independent implementation packages. A single package
dbi provides a collection of wrapper components to present the combined functional-
ity of the implementation packages to clients in higher-level groups.

Often it is possible to provide a wrapper component for a subsystem directly in an

intermediate-level implementation package (e.g., dba), thereby having to expose only
a single component header from that package to the rest of the group. As happens to
be the case in this particular example, however, it is sometimes necessary to escalate
the encapsulation (and insulation) to a higher level-in this case, to a higher-level
package within the group (e.g., db;).

With the exception of the low-level types and protocols defined in dbt, the entire
functionality of the core database group is accessible through the wrapper compo"
nents provided in db; alone. Because dbi is an encapsulating and insulating package
section 7.5 Package Groups 509

of wrapper components for dba, dbb, dbc, dbd, and dbe, there is no compelling reason
to provide clients of this group with the headers for components defined within these
implementation packages. Once we have built the db; package library, exporting
these headers to higher-level groups would serve only to clutter the global include
directory. Note again that exposing these headers is not an issue of encapsulation, but
one of insulation and abstraction.

After building the database group, we will make available to clients of the group only
the subset of headers defined in the db; and dbt packages. As a convenience to our
clients, we will combine all of our individual package libraries into a single group
library file with the associated prefix db,10 and make that file publicly available.

To clients of our core database, it will now appear as if we had implemented the data-
base as a single package, db, with two related prefixes: db; and dbt. There may now
be a temptation to rename both dbt and db; to the simpler db; but this would be a mis-
take. Within the collection ~f packages that comprise the core database group, we
may be looking at literally hundreds of thousands of lines of code. For some, this "

would be considered a large system in its own right. If we change the prefix names of
these components, we give up an important maintenance property of our system-the
prefix identifies the package where the source can be found. Furthermore, we lose our
protection against namespace collisions between these two packages.

If our solution to these problems is then to combine these two packages into a single
lOW-level package, we have given up package levelization and any reasonable ability to
develop and test our system hierarchically. We are back to the problem illustrated in
Figure 7-12. From a purely practical point of view, we must remember not to lose sight
of maintainability in our efforts to please the aesthetics of our clients (or ourselves).

10 Note that this name too must be registered to avoid collisions between other group and package
library names.
510 Packages Chapter 7

Demoting protocols and escalating wrappers within a package group

can help to avoid cyclic dependencies between exported (presenta-
tion) packages and unexported (implementation) packages.

Step back for a moment and notice that the protocols are part of the lowest-level pack-
age (dbt), not part of the presentation package (dbi). Escalating wrappers and demot-
ing protocols is a general and effective technique that can help to avoid cyclic
dependencies between the public and private packages within a group.

Low-level package partitions continue to serve many useful purposes, even though
most clients will not be concerned about internal partitioning. For example, during the
development process, it is inevitable that bugs will occur. It may then be useful to link
with versions of individual packages that have been compiled to contain debuggable
symbols. For very large systems, trying to link and debug many packages using the
debuggable versions can produce very large executables and make the entire process
exceedingly slow. The amount of disk space alone needed to hold an executable in
which every component in a group has been compiled with, the debug option can pose
a significant development burden. Highly effective, commercially available tools 11
used to detect low-level coding errors at runtime can produce executables literally
three times their normal size that run an order of magnitude slower. Having only two
alternatives-all or none-for linking with such large, special-purpose group libraries
is often not practical.

Fortunately most developers, working either within a package group or directly above
it, will probably have a good idea as to which individual packages within the group
are likely to be the ones causing the problem. These developers will know how to
adjust their link command to pull in only the appropriate special-purpose package
libraries, leaving access to the remaining package libraries unaffected. Providing the
ability to select individual specially built package libraries from within a group helps

11 An example of a particularly effective tool is Purify, from Pure Software Corporation.

section 7.5 Package Groups 511

to widen the envelope of systems that can be developed with a given set of tools on a
given hardware platform.

The size and structure of package aggregates is not bounded. In the example of Figure
7-7, these groups of packages took the form of a vertically arranged sequence. As we
will see in the next section, this vertical arrangement of groups somewhat simplifies
the internal release process. In a yet-larger system (i.e., in excess of a million lines of
source code), groups might form a tree-like or DAG-like structure (see Figure 7-19)-
perhaps to reflect the engineering management structure of the development effort. Of
course, in an actual design, the group dependencies would probably not be as regular
as the one shown in the figure.

Group Level 7:

Group Level 6:

Group Level 5:

Group Level 4: ~

Group Level 3:

Group Level 2:

Group Levell:

Figure 7-19: Hypothetical Very Large System with DAG-Like Group Dependencies
512 Packages Chapter 7

In short, groups of packages are analogous to packages of components A group 6

should consist of packages that are logically cohesive or otherwise make sense as a
single cohesive physical unit As it does with packages, the defined purpose of a
group should govern its contents; what is not germane should not be part of the group.
Of course, dependencies among groups of packages should form a directed acyclic
graph Although a package is an appropriate size for being owned and implemented
6

by a single developer, a group would be more likely to be owned by a project manager

and implemented by a development team. From a client's point of view, a group looks
just like a single huge package with a collection of closely related prefixes; however,
in all cases the integrity and uniqueness of each individual package within each group
should be preserved. Access to individual special-purpose package-level libraries is
needed during development

7.6 The Release Process

As one of many developers working concurrently on a large project, it can be difficult

to determine why your regression tests are failing-was it the change you just made to
this package or a change made to some lower-level package? Developing software in
an environment where spontaneous changes can occur affects productivity even for
small projects, and is probably unworkable for most larger projects.

Internal releases are an integral part of any large development project. Groups of
packages are the smallest unit of functionality that are normally released. At some
regular predetermined interval, the code for a group of packages (e.g, the core data-
base group, db, of the previous section) is frozen 12 and the process of building a stable
internal release begins.

DEFINITION: A layer corresponds to all package groups at a given

level of a system. _

The process of releasing a group is accomplished in an orderly, bottom-up fashion,

governed by the levelization of the packages within the group. The packages at the
lowest level in the group are built and tested in isolation. Once these packages pass
their individual, component-level hierarchical regression tests, level-2 packages can

12 The liberty to make arbitrary updates to this version of the software is suspended.
section 7.6 The Release Process 513

be built and tested, linki~g only with level-1 packages. The process of rebuilding a
system is markedly similar to the way the individual components within a package are
developed and tested, but on a larger scale.

The levelization of package groups has a special significance in the release process.
All groups at each level in the system are collectively called a layer. For systems with
vertically arranged groups (see Figure 7-17), each layer consists of only a single
group. For larger systems with more complex group arrangements (see Figure 7-19), a
given layer may consist of several groups. To ensure consistency across the entire sys-
tem, it is important that all groups' on which a given group 9 depends have been
released before code for 9 is frozen and 9 is released. For example, group dby in Fig-
ure 7-19 is at level 3. The dby group cannot update its dependencies to the new ver-
sion of group geo until the xl ate group has also been released. In contrast, group dbz
depends only on group geo and hence need not wait for the' xl ate group to be
released in order to start the update process.

By definition, all groups on a given level are independent of each other. The release
process for each of these groups can occur independently. Although not all groups at
the next higher level will depend on all groups at the previous level, tracking individ-
ual group dependencies during the release process may be more effort than it is worth.
We can simplify the release process while ensuring the consistency of the entire sys-
tem simply by insisting that all groups on a given level are released before beginning
the release process for groups at the next higher level.

When the release process for all groups on this layer is complete, the availability of
the new package groups is announced. Developers working on the next higher layer
continue to use the previous release of the lower-level layer until they reach a conve-
nient stopping point. After rerunning their own regression tests one last time, these
developers may now-at their leisure-adjust their environments to refer to the newer
release of the lower-level software.

At this point the developers may have to make changes to their own code to accom-
modate any interface changes made to lower-level package groups since the last
release-a process sometimes referred to as porting. 13 Obviously, with good planning
-
13 The term porting applies to moving a software system to a new platform. This new platform can
take the form of new hardware, a new operating system, or a new version of the lower layers of the
system itself.
514 Packages Chapter 7

such changes will be minimized. After a few minor adjustments, developers should be
able to rerun their regression tests to verify that changes to the lower-level software
have not altered the nature of the needed functionality. These developers can now
resume development, using the new stable release of the software. At some point
these clients will in tum freeze their code and go through a similar release process.

Notice how a client of the immediately preceding layer is not forced to respond imme-
diately when a new release is published. Experience has shown that providing some
slack between the release of successive layers is an effective way to manage internal
releases within a large system.

7.6.1 The Release Structure

Figure 7-20 shows one way to organize the development hierarchy for the system pre-
sented in Figure 7-18. This development-directory structure supports mUltiple releases
and the notion of header files shared among packages that are not exported outside the
group. At the root of the directory structure there are the five group directories corre-
sponding to the five groups in the system of Figure 7-17; each group has a subdirectory
structure similar to the one shown here for the core database group, db. Beneath the db
directory are subdirectories holding the past several parallel release structures of this
group; the release illustrated in Figure 7-20 for the db group is release 1.6.3.

Under the group's release directory are four directories and a file. The directories are
de pen den c i e s, sou r c e, inc 1 u de, and 1 i b, and the file is ex p 0 r ted. The dependen-
cies directory indicates the names and release versions of the other groups on which
this group depends. On a Unix-based system, each of these dependencies may be rep-
resented by a symbolic link that refers back to the specific release of the lower-level
group used to build this group. Providing these references allows the include and link
directories of clients to remain relative as they update a single pointer from the old to
the new release of a group.

The source subdirectory is organized in the same way as it was the for the much sim-
pler package-development structure shown in Figure 7-2. As Figure 7-20 indicates, all
of the source for each package within the group lives under a directory corresponding
to its package prefix, which makes it easy for developers to locate packages defined
within the group. Unfortunately, locating packages defined outside the group noW
becomes more difficult. This problem can be addressed by having packages within a
section 7.6.1 The Release Structure 515

group extend a common group prefix (e.g., dba or dbb) Of, less desirably, by identify-
ing the group location in the global package registry. There is an additional issue
involving "prefix prefixes"-that is, how does anyone know that dbq is not a legal
prefix for some new package not in group db?

ed
-
rell.6.3 rell.6.0
~

rell.6.1 -
current

dependencies source include 1i b exported

---- base dbi_cl.h libdb.a
dbi_c2.h
dbt_cl.h
dbt_c2.h
dbt_c3.h
dbt_c4.h

1oca 1 1oea 1
dba_cl.h libdba.a
libdba_9.a
dba_cn.h libdbb.a
dbb_el.h libdbb_9.a

libdbt.a
dbt_e4. h 1 i bdbt_9 . a

dba dbb dbc dbd dbe dbi dbt

------- ~
dependencies exported

source
dbe - cl.h dbe - cl.e dbe _cl.t.e
dbe - c2.h dbe_c2.c dbe- c2.t.c
.. .
dbe_ ci . h dbe - ci . c dbe - c; . t. c
...
dbe - cn.h dbe - cn.e dbe _cn.t.e

Figure 7-20: A Development Directory Hierarchy for Package Groups

516 Packages Chapter,

Configuration control must be an integral part of the development process. Systems

such as sees and ReS will need to be integrated into the development environment.
Even more powerful systems are also commercially available, but a detailed discus-
sion of the use of such tools is beyond the scope of this book.

The include directory is now more complex in order to support the notion of exported
versus local headers for this group. The subdirectory 10 cal under inc 1 ude is similar to
the global include area of Figure 7-2, but is accessible only from within the db group.
This local directory contains header files that are necessary to support interpackage
communication within this group. The contents of the file exported, defined directly
under the release for the group, identifies individual components or entire packages
whose headers are to be made available to clients external to this group. During a
release, these headers are copied directly into the included directory for the group.14

Finally, the 1 i b directory is now also more complex in order to support the notion of a
single group library. Again the subdirectory 10 cal under 1 ibis similar to the global
1 i b directory of Figure 7-2 in that this subdirectory holds all of the various versions of
the individual package library files. Instead of containing library files corresponding to
each package, 1 i b contains a single library file representing their union. Providing just
a single library file makes using the group more convenient for general clients.

As Figure 7-20 shows, more than one version of each individual package library may
be built. The suffix _9 is used to indicate that the library has debugging symbols.
Many other special forms of libraries may exist as well, for purposes such as perfor-
mance monitoring or runtime memory-bounds checking. If the group is large, it may
not be practical to use or even build special-purpose libraries for the entire group.
Instead, developers will typically identify the individual packages within the group
that they would like to analyze more carefully.

Releasing a group using this development directory structure is straightforward.

The entire directory and file structure (except for the files contained under the
inc 1ude and 1 i b directories) for this group and release is repeated under a neW
release (e.g., sy s tern/ d b / re 11 .7. 1). The dependencies for this new release (e.g.,
systern/db/rel1.7 .1/dependenci es/base) are adjusted to point to the new relea~e
. thIS
of the lower-level software (e.g., systern/base/rell.7 .1). Each package In
group is then copied to the new release, rebuilt, and tested in levelized order.

14 Symbolic links or the equivalent may replace actual copies.

section 7.6.1 The Release Structure 517

As each package is built, header files that are to be exported from the package for use
by other packages within .this group are placed in the local include directory (e.g.,
sy s tem/ db / re 11 . 7 . 1/ inc 1 ude /1 oca 1 / dba_c3 . h). At the same time, each version of
the individual package libraries is placed in the local lib directory for this group (e.g.,
s y s t em / db / r ell. 7 . 1 / 1 i b / 1 0 cal /1 i b db a . a) Once all packages local to this group
have been built, the package libraries are combined into a single library and placed in
the lib directory (e.g., system/db/rel1.7 .1/1ib/libdb.a). Only those headers that
clients of this group will need in order to use the group are then exported to the
include directory (e.g., system/db/rel1. 7 .1/i ncl ude/dbi_cl. h).

The directory cur r e ntis not published but is reserved for ongoing development.
Although changes to published versions are infrequent and carefully controlled (see
Section 7.6.2), changes to the cur r en t (development) version may be expected to
occur frequently.

We can extend this directory structure to support multiple platforms by providing an

addition node in the hierarchy just before any machine-dependent files. For example,

system/db/rell.7.1/1ib/libdb.a

would instead become

system/db/rell.7.1/1ib/sun4os4/1ibdb.a

or

system/db/rell.7.1/1ib/hppaux9/1ibdb.a

to reflect the desired combination of machine architecture and operating system.

Minimizing the time it takes to recompile after a source-code change

can significantly reduce the cost of development.

The cost of compiling is partially a function of the number of header files in an include
directory, but is even more dependent on the number of directories the compiler has to
518 Packages Chapter 7

search in order to locate all required header files. On most systems, it is Significantly
faster to compile components when all of the header files reside in just a few directo-
ries than if the headers are distributed across many individual (package-level) include
directories.

To make the cost of an excessive number of individual include directories concrete, I

devised an experiment to compare the overhead of compiling a single component
using individual package include directories, group include directories, layer include
directories, and a single global directory. I made several order-of-magnitude assumptions:

• 10 Hi ncl ude directives per component

• 10 components per package
• 10 packages per group
• 10 groups per layer
• 10 layers per system

The experiment was repeated for systems containing 1, 10, 100, 1,000, and 10,000
components on structures with varying numbers of include directories. Figure 7-21
contains the results of running the experiment both with the CFRONT compiler on a SUN
SPARC 10 workstation and also with the native C++ Compiler on an HP7000 workstation.

For reference, compiling an otherwise empty component that depends on only a sin-
gle package include directory takes approximately 1 CPU second to compile on the
SUN and 0.2 CPU seconds on the HP. As the system size increases, the cost of compil-
ing increases modestly on the SUN and only negligibly on the HP. For systems on the
order of 1,000 components, the cost of compiling a component using individual pack-
age include directories can use nearly twice the CPU time on the SUN and 4.5 times
the CPU time on the HP. For larger systems, the overhead of using individual package
include directories is even more pronounced-roughly an order of magnitude for the
SUN and nearly so for the HP. 15

15 Note that actual elapsed "wall" time can overwhelm even the CPU time when compiling compo-
nents that depend on a large subsystem. For example, the wall time to compile a component against
a 1,000-component system distributed across 100 individual package include directories was 22.1
seconds on the SUN and 4.8 seconds on the HP. When the system consisted of 10,000 components,
the wall time to compile a single component grew to 225.5 seconds on the SUN and 209.2 seconds
on the HP.
section 7.6.1 The Release Structure 519

Subsystem
Size in Number of Include Directories Number of Include Directories
Number of
Components 1 10 100 1000 1 10 100 1000

10 1.0 0.2
Time
(100%) (100%) in CPU
Relative to Seconds
Using a Single
100 1.0 1.0 Include Directory 0.2 0.2
(100%) (100%) (100%) (100%)

1,000 1.1 1.1 0.2 0.2 0.9

(100%) (100%) (182% (100%) (100%) (450%)

10,000 1.4 1.4 2.3 15.1 0.2 0.2 0.9 15.2

(100%) (100%) (164%) (1,079%) (100%) (100%) (450%) (7600/0)

CPU Time on SUN SPARe 10 CPU Time on HP 735

Figure 7-21: Compilation Time/(Overhead) Due to Multiple Include Directories

Reducing the amount of time it takes to recompile and relink can have a significant
impact on productivity. Fortunately, there are a couple of ways we can reduce this
problem for large systems short of buying a faster piece of hardware. The most effec-
tive method is to reduce the number of header files via insulation, as discussed in
Chapter 6. Another method, which will have a lesser (but still significant) impact, is to
reduce the number of include directories that a compiler needs to search during a
given compilation. One such way is to propagate the headers exported from lower-
level groups (identified by file de pen den c i e s) into a dependent group's own exported
headers directory, perhaps with additional filtering defined in file exported.

As Figure 7-22 illustrates, not all the headers exported by the base and db layers are
needed by clients of the t 1 k layer. Instead of having t 1 k simply publish just its own
headers, t 1 k could republish the necessary subset of lower-level exported headers in
addition to its own exported headers. In this way we can avoid forcing its clients to
specify the separate include directories for both bas e and db. Now clients of the t 1 k
layer need specify only one include directory in order to access the t 1 k layer func-
520 Packages Chapter 7

tionality. Here again, it is insulation that enables us to reduce the number of headers
we expose to our clients to improve their rate of compilation.

system/tlk/rell,7,l/include
system/db/rell.7,l/ioclude tlkl_cl.h
system/base/rell,7,l/ioclude dbi_cl.h tlkl c2.h
pub_cl.h dbi_c2.h tlkl c3.h
pub...;.c2.h dbt_cl.h tlk2_cl.h
usr_cl.h dbt_c2.h tlk3_cl.h
pub_c2.h pub_cl.h tlk3_c2.h
usr_c3.h pub_c2.h dbi_cl.h
usr_cl.h dbt_cl.h
pub_cl.h

Figure 7-22: Minimizing a Client's Cost of Including Headers

Another alternative is to make the client group responsible for "prefetching" all of its
required headers into a single include directory before attempting to compile. Requir-
ing the client to create a special-purpose directory to efficiently reuse a subsystem in
effect makes such a subsystem less reusable. This second approach seems less
friendly, since it forces the client to do more work to use the subsystem; however, it
can have its advantages in a hostile environment.

7.6.2 Patches

Making changes to a release is potentially disruptive to development, and so it is

important to preserve the stability of a release once it is created. Sometimes a critical
bug will be detected in a stable release that cannot wait until the next release to be
fixed. Repairing the bug and rebuilding the entire system from scratch is both disrup-
tive and time consuming, especially for the potentially large client population. If the
problem is in the implementation, it is often much more cost-effective to patch it.

DEFINITION: Apatch is a local change to previously released soft-

ware to repair faulty or grossly inefficient functionality within a com-
ponent.

The simplest, safest, and most common kind of patch involves making changes to
only the. c file of a component. After the. c file is modified and compiled, the result-
ing .0 file may then (on a Unix system) be placed before a library file in the link corn-
section 7.6.2 Patches 521

mand to supplant an existing . 0 file. Of course, clients can choose whether or not to
link-in these patch files-for some, the fix may not be worth the loss in stability.

A patch must not affect the internal layout of any existing object.

Not every bug can be patched. Fortunately, if the header file for the component is not
exported, the layout of such an object can be known only to the components within
the package. In such cases, the bug can almost always be fixed by providing one or
more patch files to solve the problem. However, even if the header file is exported,
there are a number of bugs that can be patched without having to rebuild the entire
system. The more insulated the implementation of a component, the more likely that
it can be patched without affecting components outside the package.

Consider the non-insulating class Examp 1e shown in Figure 6-49, implemented

entirely inline. If the header for Ex ampl e is exported, there is no way we could hope to
patch a bug in it. Any change we would make to the implementation of class Examp 1e
would force the recompilation of all clients that use it. Compare this now to the fully
insulating Examp 1e class of Figure 6-51, which has no inline functions, no ip.heritance,
and exposes only a single opaque pointer to its data. It is virtually certain that we could
patch any purely implementational problem, thus avoiding the need for clients of this
class to recompile.

Ideally a patch does not require modifying any header files at all. Modifying infonna-
tion in an exported header file has the potential to affect an unbounded number of cli-
ents; such changes are therefore best avoided. Although risky, there are a number of
repairs we can make that will not invalidate our release, even though it may mean
altering the existing exported header files. If we can guarantee that the effects of these
local changes are link compatible and do not invalidate the release, we can save the
considerable expense and effort of a second release.

The following kind of changes are relatively safe:

• Altering the body of a non-inline function.

• Altering any construct in the . cfile with intemallinkage.
522 Packages Chapter'

• Adding a new exported header file to the release.

• Adding a f r i end declaration to a class.
• Relaxing an existing access specifier (e.g., from protected to publ i c).
• Adding a new non-virtual function to a class (risky).
• Adding a class or free operator to a header (risky).

Note that the last four examples require modifying a header file. After such a change,
this header file should be artificially backdated to prevent unnecessary recompilations
by clients. The last two examples are risky because of the possibility of introducing an
ambiguity from function or operator overloading in a header file that has already been
included by some client. Had the last example been introduced in a new and separate
header file, there would be no chance that the construct would affect any existing usage.

The following changes can potentially corrupt a release:

• Adding, reordering, modifying, or removing any data members.

• Adding, reordering, or removing any virtual function.
• Changing the signature or return value of any function.
• Adding, reordering, modifying, or removing any inheritance relationships.
• Altering any construct in the header with internal linkage.
• Reducing the access of a class member (e.g., from protected to private).
• Introducing an access specifier between adjacent data members. 16

The lists presented here are not complete, but should give the idea and flavor of the
kinds of changes that, if made carefully, can be accomplished locally via patches. The
only real requirements are that:

1. We ensure link-time compatibility after the patch.

2. We avoid causing our clients to recompile because of changes in header-

file time stamps.

3. We are sure that the system would successfully rebuild if we were to try
to do so.

16 See ellis, Sections 9.2, p. 173; and 11.1, pp. 241-247.

section 7.7 The rna i n Program 523

There is much more to creating an effective development environment than can be

presented here. The techniques used will depend on the operating system. Organiza-
tions similar to those illustrated in Figure 7-20 have been used successfully on Unix-
based systems to develop very large projects.

7.7 The rna; n Program

When we write a program in C++, we are required by the language to provide a

unique definition of the function rna into interface with the operating system and, in
particular, to process any command line arguments. However, when we invest tens,
hundreds, or even thousands of staff years to create a C++ system, there is no single
top to the system. That is, invariably there are several executables, each with its own
rna i n procedure, that together comprise the system. Instead of producing a single pro-
gram, our design methodology has created a hierarchical collection of reusable sub-
systems. Many of these subsystems will be used in standalone input verifiers,
translators, viewers, report generators, output analyzers, and so on. The number of
individual "main" programs is likely to grow as the system evolves and matures.

Factoring independently testable and potentially reusable functionality

out of a translation unit that defines rna i n enables essentially the entire
implementation of the program to be reused in a yet larger program.

The purpose of a translation unit defining rna i n (other than a hierarchical test driver) is
to provide a C++ subsystem with a command line interface, interpret environment
variables, and manage global resources-nothing more. A common mistake is to
place far too much code in a file that defines rna i n. Such code cannot be tested incre-
mentally from a C++ test driver, nor can it be reused within a larger C++ program.

For example, consider a program designed to perform some sort of desktop publishing
function-say a glossary generator, illustrated in Figure 7-23. The function of a glos-
sary generator is to read an input document and store it as a set of unique words. This
input is filtered against a second input defining a set of blocking words. Blocking words
are common words (such as and, this, a, etc.) that are likely not to be appropriate for a
524 Packages Chapter 7

glossary. Next, the remaining set of words is compared against a third input, a thesaurus ,
that in this context represents a mapping of aliases or alternate forms to more common
or basic terms. For example, method is another name for member function in C++.
Finally, all basic tenns that are not blocked or alia sed must be defined in a fourth
input-a dictionary. A dictionary is a mapping from a set of common terms to their
respective definitions. The outputs of the glossary generator are a list of undefined tenns
and the' alphabetized subset of the definitions in the dictionary corresponding to
recognized terms.

Input Text •
Glossary-Generator • Unrecognized Terms
Blocking Words - • Program

Thesauru s • • Glossary

Die tionary •
Figure 7-23: Glossary-Generator Program

Where should we begin the design of this program? In a top-down approach we

should probably begin with rna in, right? Perhaps. However, we should be diligent in
our efforts to factor out the implementation of functionality provided by rna i n into
independently testable and potentially reusable components. (Recall the technique of
factoring to reduce complexity of unmanageably large components presented in Sec-
tion 5.9.) How we will import the information from the command line is only one of
our concerns. Another important question we should be asking is how the underlying
functionality might some day conveniently be integrated into a larger program (e.g., a
desktop publishing framework). To achieve a modular design, we must simulta-
neously address the underlying programmatic interface and the standalon-e command-
line interface for the immediate end user.

A central piece in the design of a glossary-generator program is very likely a glossary-

generator object defined in a glossary-generator component, such as the one illustrated
in Figure 7-24. In order to use a glossary-generator object, we first need to program it
with blocking words, aliases, and dictionary definitions. Explicit manipulator functions
Section 7.7 The rna i n Program 525

in the d t p_G los s Gen class are provided for these purposes. After the glossary generator
is programmed, we can load the individual words of the input text into the glossary-
generator object using the addTextWord manipulator function. Once we are done load-
ing all the input text for the document, we will create an iterator to sequence over the
glossary definitions in alphabetical order. A second iterator is provided to allow us
to sequence over any undefined terms. Having completed processing on a first doc-
ument, w.e may wish to pass several related documents through the same generator.
The c 1ear I nput W0 r d s manipulator allows us to start again with a new document while
retaining the previously programmed blocking words, aliases, and definitions.

/1 dtp_glossgen.h
#ifndef DTP_INCLUDED_GLOSSGEN
#define DTP_INCLUDED_GLOSSGEN

class dtp_GlossDefIter;
class dtp_GlossUndefTermlter;

class dtp_GlossGen_i: // fully insulated.implementation

class dtp_GlossGen {
atp_GlossGen_i *d_this;

friend dtp_GlossDefIter;
friend dtp_GlossUndefTermIter;

private:
// NOT IMPLEMENTED
dtp_GlossGenCconst dtp_GlossGen&);
dtp_GlossGen& operator~(const dtp_GlossGen&);

public:
// CREATORS
dtp_GlossGen():
-dtp_GlossGen():

// MANIPULATORS
int addBlockingWord(const char *blockingWord);
int addAlias(const char *alias, const char *keyTerm);
int addDefinition(const char *keyTerm~ const char *definition);
int addTextWordCconst char *textWord);
void clearlnputWords():
};

class dtp_GlossDeflter_i; // fully insulated implementation

class dtp_GlossOeflter {
dtp_GlossDeflter_i *d_this;
526 Packages Chapter 7

private:
II NOT IMPLEMENTED
dtp_GlossDefIter(const dtp_GlossDeflter&);
dtp_GlossDefIter& operator=(const dtp_GlossDefIter&);

public:
II CREATORS
dtp_GlossDefIter(const dtp_GlossGen& glossaryGenerator);
~dtp_GlossDefIter();

II MANIPULATORS
void operator++();

II ACCESSORS
operator const void *() const;
const char *keyTerm(); II Provides an association
canst char *definition(); II (keyTerm. definition) so
II we choose not to define an
II operatorC)() here.
};

class dtp_GlossUndefTermIter_i; II fully insulated implementation

class dtp_GlossUndefTermIter {
dtp_GlossUndefTermIter_i *d_this;

private:
II NOT IMPLEMENTED
dtp_GlossUndefTermlter(const dtp_GlossUndefTermIter&);
dtp_GlossUndefTermlter& operator=(const dtp_GlossUndefTermlter&);

public:
II CREATORS
dtp_GlossUndefTermIter(const dtp_GlossGen& glossaryGenerator);
~dtp_GlossUndefTermlter();

II MANIPULATORS
void operator++();

II ACCESSORS
operator const void *() const;
const char *operatorC)() const; II Returns just the current undefined
}; II term so operator()() is ok here.
#endif

Figure 7-24: Insulating Interface for a Glossary-Generator Wrapper Component

Our rna i n will still need to create a dt p_G 1 os sGen object and then translate input from
(files referenced by) the command line into dtp_Gl ossGen member function calls in
order to program this object appropriately. However, we may elect to use any number
section 7.7 The rna i n Program 527

of input grammars in order to program the glossary generator. It would therefore be

inappropriate to tie the programmatic interface of the glossary generator to anyone
syntax. Instead, we create a separate component responsible for reading some given
input, parsing that input, and exercising the glossary-generator component accord-
ingly. The highest levels of the glossary generator program's component architecture
are shown in Figure 7-25.

n+2
main()

Lower-Level Components (see Figure 3-16)

Figure 7-25: High-Level Glossary Generator Program Architecture

The job of the interpreter component, illustrated in Figure 7-26, is to attach itself to a
glossary-generator object and then exercise that object accordingly, based on com-
mands found in a specified input file or stream. The interpreter object itself is pro-
grammed with two pieces of information:

1. The address of the glossary generator it is to manipulate.

528 Packages Chapter 7

2. The error output stream to which the interpreter is to report detailed

syntax error messages.

II dtp_glossgeninterp.h
#ifndef DTP_GLOSS_GEN_INTERP
#define DTP_GLOSS_GEN_INTERP

class dtp_GlossGen:
class ostream;
class istream;

class dtp_GlossGenlnterp_i;
class dtp_GlossGenlnterp {
dtp_GlossGenInterp_i *d_this;

private:
II NOT IMPLEMENTED
dtp_GlossGenlnterp(const dtp_GlossGenlnterp&);
dtp_GlossGenlnterp& operator=(const dtp_GlossGenlnterp&);

public:
I I CREATORS
dtp~GlossGenInterp(dtp_GlossGen* glossGen);
II create an interpreter
~dtp_GlossGenInterp();
II destroy this interpreter
II MANIPULATORS
void setErrorStream(ostream& errorStream);
II Set output stream to which detailed errors will be reported.
II By default, this stream is cerro
II ACCESSORS
int exercise(const char *fileName = "_") canst;
II Parses commands from the specified input file. Returns
II -Ion 1/0 error, 0 on success and 1 on syntax error.
9

II The default "_" stands for "standard input" (i.e., cin).

int exerciseCistream& input, const char *fileName = 0) canst;
II Parse commands from the specified input stream. Returns
II -1 if an liD error occurs; otherwise returns the line
I I number of the fi rst syntax error. If successful thi s
t

II function returns O. The second argument is used only

II for the purpose of identifying the input source when
II formatting syntax error messages to the error stream.
};

#endif

."'igure 7-26: Fully Insulating Interpreter Component for Glossary Generator

Section 7.7 The rna ; n Program 529

Two accessor functions of the interpreter are provided to exercise the functionality of
the associated glossary-generator object. The first simply takes a file name and opens
it if possible. This function then calls the second (more primitive) form, which takes
an open stream and an optional "file" name to be used in formatting error messages.
The lower-level function is exposed in the interface so that the source of the stream
need not be an actual file. Note that these two member functions do not affect the state
of the interpreter; they affect only the state of the glossary generator.

Finally, all that is left to do in rna in is to create these two objects and sequence
through a set of command-line arguments. If no command-line arguments are speci-
fied,c i n should be assumed by default. A tiny standalone main driver for the glossary
generator program is shown in Figure 7-27. This driver illustrates a reusable pattern,
suitable to a variety of standalone applications.

II dtp_glossgeninterp.t.c
II
II Usage: a.out [ <file name> I - J*
II
II Example:
II
II john@john: a.out stuff.abc such.def -
II
II The above command line will first read input from the file
II "stuff.abc", then read input from the file "such.def", and
II finally read from standard input (cin).
#include IIdtp_glassgeninterp.h"
#include "dtp_glassgen.h"
canst char *const defaultArgs[] - { "_n};
1111, II has internal linkage
canst int defaultNumArgs = sizeof defaultArgs I sizeof *defaultArgs;
main(int argc, char *argv[J)
{
int status = 0;
canst char *progName = argv[O]:
int numArgs = argc > 1 ? argc : defaultNumArgs;
canst char *const *args = argc > 1 ? argv : defaultArgs;
dtp_GlossGen glossaryGeneratar;
dtp_GlossGenlnterp interpreter(&glossaryGenerator);
for (int i - I ; i < numArgs && 0 == status; ++i) {
status = interpreter.exerciseCargs[i]):
}

return status;
}

Figure 7-27: A Standalone Main Driver for Glossary Generator and Interpreter
530 Packages Chapter 7

Ownership of rna incomes with both privilege and responsibility. There is only one
rna in in a given program. It is this piece of code that should be responsible for reading
environment variables and establishing global resources. The person who owns ma in
owns the global name space. For example, there is no harm if the file containing rna in
defines or accesses external global variables, fails to use package prefixes, and so
forth. To ensure our ability to integrate arbitrary subsystems, however, no other part of
the system should pollute the global name space or attempt to usurp a global resource.

Guideline:
In general, avoid granting one component license that, if also taken
by other components, would adversely impact the system as a whole.

This (Kant-like) philosophy implores that unless we define rna in, we should not
attempt to do something that, if others did it also, would have a negative consequence
for the overall system.

Excessive use of inline functions is just one example of the kind of behavior that can
lead to subtle integration problems down the road. By cavalierly declaring inappropri-
ately large member functions inline, we can often improve the runtime performance
of our own object in isolation or within a small subsystem. However, this runtime
improvement is obtained at the cost of repeated code and increased executable size.

When such selfishly architected subsystems are integrated into larger subsystems, the
increased code size begins to show its adverse effect. Hardware mechanisms designed
.
to improve the performance of commonly used routines are defeated by the exceSSIve
repetition of inline code. The increased program size reduces the percentage of the
executable that the operating system can keep in core, which leads to increased swap-
ping. At some level of integration, many of these objects will actually begin to run
more slowly (as a result of the excessive inlines) than they would have run had so~e
of the larger functions been declared non- i n 1 i ne. The end result of this selfishness IS
a net decrease in overall system performance.
section 7.8 Start-Up 531

Another case in which a lack of diligence by individual developers can adversely

affect an integrated system involves the indiscriminate use of non-local static objects,
as discussed in Section 7.8. Yet another specific case of avoiding such egocentric
behavior on the part of a component or subsystem is discussed in the context of class-
specific memory management in Section 10.3.4.2.

lVlajor Desigll Rllle

Only the . c file that defines rna i n is authorized to redefine global new
and del ete.

An important special case of this philosophy is that only the owner of rna i n can be
authorized to redefine the global operators new and del et e. Components that do not
define rna i n are proscribed from such unilateral behaviors. Otherwise two indepen-
dent subsystems, each redefining a unique resource (such as global operator new),
would not be link compatible.

To summarize: there is no top when designing a large system. The purpose of rna in is
only to provide a C++ subsystem with an interface to the command line, interpret envi-
ronment variables, and manage global resources-nothing more. Factoring functional-
ity provided by rna i n into separate components facilitates hierarchical testing and
enables easier integration into yet larger systems. The. c file that defines rna in owns the
global name space and is exempt from certain design rules that pertain to ordinary com-
ponents. For components that do not define rna i n, care should be taken not to take liber-
ties that, if also taken for other components, could compromise the system as a whole.

7.8 Start-Up

The elasped time between when a program is first invoked and when the thread of
control enters rna in is referred to in this book as start-up. It is during this time that
potentially all non-local static objects in every translation unit are constructed, as
illustrated in Figure 7-28. 17

17 According to the C++ language specification (ellis, Section 3.4, p. 19), all non-local static objects
within a translation unit must be constructed prior to the first use of any function or object defined
within that translation unit; in practice, however, all such initializations can and commonly do occur
at start-UD.
532 Packages Chapter 7

DEFINITION: Start-up time (also known as invocation time) is the

time between when a program is first invoked and when the thread of
control enters rna; n.

II my_component.c
#include "my_component.h" II defines class my_Class
#include "pub_list.h" II defines class pub_List
#include <sys/types.h> II declares typedef time_t
#include <sys/time.h> II declares ::time()

II static object at file scope

static pub_List list; II constructed at start-up
II static dQta member initialized by function call
static time_t startUpTime = time(O); II called at start-up
II static object in class scope
pub_List my_Class: :d_List; II constructed at start-up
II

Figure 7-28: Initialization of Non-Local Static Variables at Start-Up

Since the order of initialization between non-local static objects defined in separate
translation units is implementation dependent, special care must be taken to ensure
that such static objects are initialized before they are used. When the intent is to pro-
vide a single instance of a globally accessible object, our stated aversion to global
data (Section 2.2) leads us to look for an alternative. Instead of creating an instance of
an object at file scope with extemallinkage, we can usually achieve our purpose with
a logical construct commonly referred to as a module and implemented in C++ as a
class containing only static members. I8

18 A module can also refer to a physical entity that is similar to a component, but that has a procedural
interface. Note that, in ANSI C, the only way to implement a logical module is as a physical module
(Le., as a separate translation unit defining static data at file scope). For more about modules, see
stroostrup, Section 1.2.2, p. 16.
section 7.8 Start-Up 533

Guideline
Prefer modules to non-local static instances of objects, especially when:
1. Direct access to the construct is needed outside a translation
unit.
2. The construct may not be needed during start-up or immedi-
ately thereafter and the time to initialize the construct itself is
significant.

The need to ensure the proper initialization of static constructs before they are used is
well documented. 19 What is less commonly appreciated is the magnitude of the com-
bined impact such initializations can have on start-up time. For small programs, ini-
tializing a few static constructs at start-up would probably have no noticeable impact
on a user's perception of the time needed to invoke the program. However, the larger a
system is, the more opportunity there is for independent static constructs to require
initialization during start-up.

The construction of each non-local static objects in a program

potentially contributes to invocation time.

Since every static object defined at file scope or within class scope is potentially con-
structed before rna i n is entered, a very large system whose components regularly
define such static objects could take an unacceptably long time to bring up. In fact,
there are documented cases of very large (supposedly interactive) systems where
naively ignoring the cost of initialization at start-up has resulted in invocation times in
excess of 10 minutes!

19 ellis, Section 3.4, p. 20; meyers, Item 47, p. 178. .

534 Packages Chapter 7

Non-local static objects are initialized and destroyed automatically by the C++ runtime
system; their indiscriminate use by individual components is a form of egocentric
behavior that degrades the invocation performance of integrated systems. Although
there is nothing we can do to stop these static instances from being initialized at start-
up, there is considerable flexibility about how and when modules are initialized. Fortu-
nately, it is always possible to transform a single global instance of an object into a
module that, when initialized, dynamically allocates that object. 2o Once initialized, the
module can successfully return a reference to the dynamic object it now holds.

7.8.1 Initialization Strategies

There are at least four different techniques that can be used to ensure that a module is
initialized before it is used:

.. Wake-up initialized
• Explicit i nit function
• Nifty counter
• Check every time

Each of these initialization strategies has its own advantages and disadvantages; the
best choice will depend on several factors:

• The time required to initialize the module

• The likelihood that the module will actually get used
• The amount of work done per module function call
• The frequency with which calls to module functions are made
• The number of components that use the module directly
• Whether there is a need to free/reallocate resources before the program exits

7.8.1.1 The Wake-Up Initialized Technique

By far the best way to initialize a module is to try to have the module "wake up" in an
initialized state. For example, using this wake-up approach, a global registry module
might be implemented as a list of record links, as shown in Figure 7-29.

20 See the Singleton design pattern in gamma, Chapter 3, pp. 127-138.

section 7.8.1.2 The Explicit ; n ; t Function Technique 535

II ax_registry.h
#ifndef INCLUDED_AX_REGISTRY
#define INCLUDED_AX_REGISTRY

class aX_RecordLink;
class ax Record;

class ax_Registry {
static ax_RecordLink *d_list_p;

public:
static void addRecord(ax_Record *record);
II Add record to registry; registry now owns the record.

static void cleanup();

II Free all dynamicly allocated memory: reset to empty.

II
}; II ax_registry.c
#include "ax_registry.h"
#endif ax_RecordLink *ax_Registry: :d_list_p = 0;
I I ...

Figure 7-29: Module that Wakes Up Already Initialized

As long as all the static data members are fundamental types (pointers,21 integers,
doubles, arrays of characters, etc.), they will be initialized at load time (i.e., prior to
start-up) without affecting invocation time. Had we instead embedded a pub_L i st
object (Le., not just a pointer) as a static member of class ax_Reg i s try, then that
member would get initialized automatically (during start-up), incurring a runtime cost..

7.8.1.2 The Explicit; n; t Function Technique

Not all modules can wake up initialized. More generally, some components may
define modules or contain static constructs that must be initialized at runtime before
they can be used. One way to enable this initialization is to provide each such component
with an i nit function, as illustrated in Figure 7-30. This i nit function must be called (at
least once) before the static constructs provided by the component can be used. The
in it-function approach is quite flexible in that the initialization can be deferred until

21A non-local static pointer to a user~defined type can be initialized at load time; in particular,
initialization to 0 is common.
536 Packages Chapter 7

well after the start-up phase and invoked only if and when the component is actually
needed.

II ax_table.h
#ifndef INCLUDED_AX_TABLE
#define INCLUDED_AX_TABLE

class ax_RecordLink;
class ax_Record;

class ax Table {
static ax_RecordLink **d_array_p;
static int d_size;

public:
static void init(int size);
static void cleanupC);
static int addRecordCconst ax Record& record);
I I ...
};
II ax_table.c
#include "ax table.h"
#endif #include "pub_List.h"
#include <memory.h> II declare memset
I I ...

II global within this

II component only

void ax_Table: :init(int size)

{
if Cd_array_p) return;
d_size = size;
d_array_p = new ax_RecordLink *[sizeJ;
memsetCd_array_p, 0, size * sizeof *d_array_p);
}

II

Figure 7-30: Providing a Component with an Explicit In i t Function

Although flexible, the explicit-i ni t-function approach is quite error prone; clients com-
monly forget to initialize a component before using it, often resulting in a fatal runtime
error. To mitigate this problem, we might provide a distinguished component at the .
section 7.8.1.3 The Nifty Counter Technique 537

package level (e.g., ax_package) with an i ni t function that initializes any component
requiring runtime initialization defined within this package. At the same time it could
also call the i nit functions for all other packages upon which this package depends.

Initializing components on which you do not otherwise directly

depend can significantly increase CCD.

The package-level i nit-function approach has some serious drawbacks. First, there is
the obvious maintenance burden of ensuring that the i nit function of every contained
component and of every package upon which these components depend gets called by
the package-level init function. Much more problematic is that initializing the entire
package can dramatically increase coupling, potentially drawing in many components
at link time that are not otherwise needed. It is for this latter reason that the use of
package-level i nit functions are best avoided-especially for a generally reusable
package with a horizontal dependency structure. Instead, it is preferable for compo-
nents that depend directly on other components requiring explicit initialization to ini-
tialize such components individually. The client component may in tum supply an init
function for use by its own direct clients, or instead may incorporate some other ini-
tialization technique. Maintaining the initialization graph at a fine level of granularity
helps to keep the CCD of a system to a minimum.

7.8.1.3 The Nifty Counter Technique

When static objects use other static objects, the initialization problem becomes more
complex. For the sake of illustration, suppose that the global pub_L i st object of Figure
7 -30 itself makes use of a static construct that also requires runtime initialization (e.g.,
for class-specific memory management, as discussed in Section 10.3.4). Trying to create
a pub_L i st as a static object at start-up before the pub_L i st's static memory manage-
ment has been initialized could easily cause a fatal runtime error. Since the relative order
of these two initializations is implementation dependent, special precautions must be
taken.
538 Packages Chapter 7

II pub_list.h
#ifndef INCLUDED_PUB_LIST
#define INCLUDED_PUB_LIST

I I ... II pub_list.c
#include "pub_List.h"
class pub_List {
I I ... I I ...
};
static int s_niftyCounter = 0:
struct pub_ListInit {
pub_ListlnitC); pub_Listlnit::pub_Listlnit()
""pub_ListInitC); {
} pub_listInit; if (0 == s_niftyCounter++) {
II init pub_list's static constructs
#endif }
}

pub_Listlnit::""pub_ListInitC)
{
if (0 == --s_niftyCounter) {
II clean-up pub_list's static constructs
}
}

Figure 7-31: Using Nifty Counters to Ensure Initialization Before Use

Instead of the error-prone i n i t- function approach, we might .consid~r using the nifty-
counter approach.22 In this approach, a dummy static instance of an initialization class
is placed in the header file of a component at file scope, as shown in Figure 7-31. Part
of the purpose of this static instance is to count the number of other components that
include this component's header. Each static instance of this dummy object included
by a translation unit will be constructed during start-up (in some order). The first time
a static instance of the dummy object is constructed, the static count is increased from
o to 1, and the dummy object knows to initialize its component. 23 Each subsequent
time a dummy instance is constructed, the only effect is to increment the static count.

22 The nifty-counter approach is discussed in ellis, Section 3.4, pp. 20-21.

23 Note that the use of any non-inline function defined within a translation unit will trigger the con-
struction of all non-local static instances defined within that translation unit.
Section 7.8.1.3 The Nifty Counter Technique 539

At program exit, the process is reversed; the destructor for each dummy object decre-
ments the static count. When this count reaches 0, the dummy object knows it is OK
to clean up the component. i ostream uses the nifty-counter technique to ensure that
c in, co ut, c err, and c log are initialized before they are used.

The beauty of the nifty-counter approach is that it is foolproof. It is not possible to use
a component requiring runtime initialization without first including its header. Doing
so causes a dummy object to get constructed, which in tum forces an uninitialized
component to become initialized. All this happens before the translation unit that
included the component's header can make use of the newly supplied declarations to
access the component. Thus a class that employs the nifty-counter method of initial-
ization may safely be instantiated statically, even if the class itself uses other non-
local static objects that also employ this technique.

Another benefit of using the nifty-counter approach is that only those components in a
package that are actually needed in order to link are initialized. The runtime cost of
the nifty-counter initialization mechanism itself is negligible except for pathological
designs containing N components depending directly on M modules, where both N
and M are large. Normally this overhead is not large when compared with the con-
struction of the first static object that does the real work of initializing the component.

The major disadvantage of using nifty counters is that even components that only
might be used at runtime are initialized at start-up anyway. For dynamic libraries that
are loaded into a running program on demand, a non-local static initialization often
requires dragging these libraries in at start-up, which defeats the purpose of demand
loading. If the amount of work done during the initialization itself is large (e.g., load-
ing a multi-dimensional table), it would be wise to consider using another technique
that allows us to defer this initialization until later in the execution of the program.

Non-local static objects are commonly used to load a collection of independent con-
crete types into a global registry at start-up. However, linking to some library imple-
mentations (such as archive files on a Unix system) will not incorporate a translation
unit's . a file unless there is an explicit reference to an external symbol that is resolved
by this .0 file.
540 Packages Chapter 7

Figure 7-32: Component/Class Diagram of System with Automatic Initialization

Consider the system illustrated in Figure 7-32. An a x_Reg i s try (see Figure 7-29) is a
module that acts as a global repository for various kinds of concrete records (e.g.,
my_Record) derived from the protocol class ax_Record. Since it is expected that there
will be many different record subtypes, a special helper class, a x_R e 9 i s t r a r, is avail-
able to aid in the automatic addition of concrete record types into the global registry at
start-up. Component ax_reg; stra r is presented in Figure 7-33.
Section 7.8.1.3 The Nifty Counter Technique 541

II ax_registrar.h
#ifndef INCLUDED_AX_REGISTRAR
#define INCLUDED_AX_REGISTRAR

class ax Record;

struct ax_Registrar {
ax_RegistrarCax_Record(*)(»;
'"'"'ax_Registrar();
};
II ax_registrar.c
#endif #include "ax_registrar.h"
#include "ax_registry.h"

static int s_niftyCounter = 0;

ax_Registrar: :ax_Registrar(ax_Record(*cfp)(»
{
++s_niftyCounter;
a x_ Reg i s try: : add ( ( * c f P) ( ) ) ;
}

ax_Registrar::'"'"'ax_Registrar()
{
if (--s_niftyCounter (= 0) {
a x_Re 9 i s try: : c1e an up ( ( * c f p ) ( ) ) ;
}
}

Figure 7-33: ax_Reg; stra r Object Used to Register Records at Start-Up

To register an instance of a record type such as my_Record, a non-local static instance

of the a x_R e 9 i s t r a r class is defined in the . c file of component my _ r e cor d as shown
in Figure 7-34. Merely linking my _reco rd. 0 into an executable image is enough to
guarantee that it is registered in the global record registry of the system. But if
my_record.o is part of a Unix library archive, there is no explicit reference to ~aw it
in at link time. That is, linking to concrete records defined in a collection of . 0 files
will work as expected, but, unless explicitly referenced, linking to the same objects
defined in a Unix library archive will have no effect; after start-up the global registry
will be empty!
542 Packages Chapter 7

II my_record.h
#ifndef INCLUDED_MY_RECORD
#define INCLUDED_MY_RECORD

#ifndef INCLUDED_AX_RECORD
#include "ax_Record.h"
4Fendif

class my_Record: public ax_Record {

I I ...
public:
static ax_Record *create();
my_Record ( ) ;
I I ...
}; II my_record.c
/finclude "my_record.h"
1fendif tfinclude "ax_registry.h"

static ax_Registry s_dummy(&my_Record: :create);

ax_Record *my_Record: :create()

{
return new my_Record;
}

II

Figure 7-34: Using ax_Reg; strar to Register my_Record

If concrete record objects reside in such a library archive, there must be some explicit
link-time dependency in order to draw them in. One solution is to provide an empty
non-inline i nit function to be called by rna i n. However, we can avoid the dependency
of derived-record objects on the registry by escalating the registration process to a
higher level (e.g., rna in). In so doing we both improve flexibility and reduce the CCD.
The modified architecture using explicit initialization is shown in Figure 7-35.
section 7.8.1.4 The Check-Every-Time Technique 543

Figure 7-35: Component/Class Diagram of System Using Explicit Initialization

Identifying which particular derived-record types are to be incorporated in a given

executable must be done somewhere. The appropriate types can either be installed
explicitly by the component that defines rna i n or externally to the program through
configuration management. The fact that a seemingly elegant initialization technique
will fail to work properly when incorporated into certain libraries underscores the
importance of physical design.

7.8.1.4 The Check-Every-Time Technique

The larger the program, the less likely it is that we will use all of the functionality it
provides. Infrequently used subsystems may still require significant work to initialize
at runtime. As with insulation, if each function call of a component already performs
a non-trivial task, adding a small amount of additional runtime overhead on each call
will probably not noticeably affect runtime performance.
544 Packages Chapter 7

II ax_ledger.h
#ifndef INCLUDED_AX_LEOGER
#define INCLUOED_AX_LEOGER

class ax_Record;

class ax_Ledger {
I I ...
public:
static int addRecord(const Record& record);
static void cleanup();
I I ...
};
II ax_Ledger.c
lIen dif #include "ax_ledger.h"
I I ...

static s_initFlag = 0;

static void init()

{
s_initFlag = 1;
II initialize component's static constructs
}

inline void s checklnit()

{
if (!s_initFlag) {
init();
}
}

int ax_Table::addRecord(const Record& record)

{
checklnit();
II now go ahead and add a record
}

void ax_Table::cleanup()
{
II clean-up component's static constructs
s_initFlag = 0;
}

II

Figure 7-36: Check Every Time and Initialize if Necessary

section 7.8.2 Clean-Up 545

Using the check-every-time technique illustrated in Figure 7-36, we do not need to

initialize the component explicitly. Instead, we make sure that each function within
the component that depends on internal static constructs first checks whether the com-
ponent has been initialized; if not, the function initializes the component immediately.
The advantages of the check-every-time approach are that it is also foolproof (for cli-
ents, anyway) and that initialization need not occur at start-up. By deferring the ini-
tialization until needed, we reduce invocation time and pay at runtime only for what
we use. i ostream employs this technique to allocate buffer space for a stream object
the first time it is used (see Section 10.3.3). The disadvantage of checking on every
function call is that it is often not practical for heavily used, lightweight objects. We
must also remember to include this initialization check whenever we add a new func-
tion to our component.

7.8.2 Clean-Up

Often just exiting the program will accomplish what our general users want; however,
as responsible developers, we must always consider the testability of our designs.
There are several ways of verifying that our code does not "leak" memory; however,
holding onto memory indefinitely is sometimes hard to distinguish from an actual
leak-especially in regression tests. Constructs, such as mUltiple inheritance, that
cause dynamically allocated memory to be managed by a pointer to anywhere other
than the beginning of the allocated block make it difficult even for sophisticated tools
to distinguish legitimate use from leaked memory.

l\1ajor Design Rllle

Provide a mechanism for freeing any dynamic memory allocated to

static constructs within a component.

By providing a clean-up function for each component containing static variables or

objects that might harbor dynamically allocated memory, we help to ease the burden
of detecting memory leaks. This requirement is presented as a major design rule
because a single non-compliant component could affect the testability of any compo-
nent that needs it.
546 Packages Chapter 7

One mixed blessing of the nifty-counter approach is that the destructor of the dummy
object can be used to initiate the clean-up of a static construct automatically. This is
good news for quality assurance, but it can present a burden for users who would pre-
fer, for perfonnance reasons, simply to exit. Fortunately we can always supply a
"switch" in order to program whether clean-up is actually to occur at program exit.
The benefit of providing this extra clean-up capability is an extra measure of quality;
the only real cost is that of additional development time and of a small amount of
extra complexity in the interface.

7.8.3 Review

To summarize this entire section: initializing modules and non-local static objects at
start-up can make the time to invoke a large program unacceptably long. Although we
cannot affect the point in the program at which these static instances are initialized, it
is always possible to transform a single global instance of an object into a module. An
effective way to ensure initialization without runtime cost is to design the module or
component to wake up initialized by having only fundamental static data members
(which are initialized at load time). Another approach to reducing invocation time is
to defer initialization until it is actually needed. This deferred initialization can be
accomplished using individual i nit functions or with initialization checks built into
every access. The i n i t- function approach is the most flexible and also the most error
prone, but it may be necessary when the individual access functions are lightweight
and called frequently. Explicit initialization is also required when attempting to link-
in self-initializing components stored in a Unix-style library upon which there is no
explicit link-time dependency. The check-every-time approach is foolproof for clients
and especially appropriate when the work done in each function call is already sub-
stantial. Finally, if we know we are likely to need a component initialized immedi-
ately upon invocation and its functions are lightweight and called frequently, the
nifty-counter approach may be the best choice after all. In all cases, providing a mech-
anism to free any dynamic memory held by static constructs (before the program
exits) will facilitate regression testing for memory leaks.

7.9 Summary

In this chapter we fonnalized the notion of a package as an aggregate cohesive unit of

physical design. A package is a natural consequence of top-down design that serves as
both an abstraction for architects and as a partition for developers. Every package
Section 7.9 Summary 547

consists of an acyclic hierarchy of cooperating components. The file names for each
component within a package and each global construct defined within that component
should begin with the registered prefix allocated to that package. The dominant pur-
pose of this prefix is to identify in which package the definition of a given component
or class can be found. Consistent use of package prefixes partitions the global name
space, which avoids name conflicts during package integration.

Dependencies between components within a package form a levelizable hierarchy. To

test components hierarchically within a package, components contained within other
packages are presumed to be correct; each external component has a level number of
o with respect to local components. Components that do not depend on other compo-
nents within the same package are defined to have a local component level number of
1. However, if package boundaries were removed, these components would not neces-
sarily have an absolute component level of 1. Local components that do not depend on
any other components within the system (called leaf components) have both a local
and an absolute component level of 1. Placing these leaf components within the pack-
ages that use them helps to improve the modularity and reusability of the system.

Dependencies among packages are defined by the envelope of the individual depen-
dencies between the components that comprise the packages. For reasons relating to
development, marketing, usability, production, and reliability, it is required that the
aggregate dependencies among packages are acyclic. Packages with acyclic depen-
dencies form a levelizable hierarchy that is completely analogous to component level-
ization. Most of the techniques discussed in Chapter 5 for reducing the coupling
between individual components apply to packages as a whole. In particular, escala-
tion, demotion, and factoring are commonly used to reduce the development costs
associated with interpackage dependencies.

Insulation at the package level includes reducing the number (and size) of header files
that must be exported for clients to use the package. Insulating clients of a package
from a particular component contained within the package requires that the compo-
nent itself is not used directly by external clients of the package as a whole, all
exported components that use this component insulate its definition from external cli-
ents, and the individual component is not independently reused by other packages.
Whenever we insulate our clients from the underlying complexities of a subsystem,
we are likely to have improved both its usability and maintainability.
548 Packages Chapter'

Just as packages partition a system into levelizable hierarchies of components, pack-

age groups partition a large system into levelizable hierarchies of packages. Princi-
ples, such as logical cohesion and avoiding cyclic dependencies, that applied to the
composition of individual packages and the interdependencies among them apply also
to package groups as a whole. The library file for individual packages may be merged
into a single group library file for the convenience of clients at higher levels; however,
specially instrumented versions of individual package libraries should continue to be
made externally accessible during development. Every package used in a system must
continue to have a unique associated prefix irrespective of any package grouping.

Internal releases are an integral part of any large development project. A directory
structure capable of supporting versioned releases was presented in Section 7.6.1.
Very large systems can be partitioned into horizontal bands of package groups called
layers. A layer corresponds to all groups on a given level. A levelizable system can be
released in stages, starting at the bottom layer (group level 1) and progressing to
higher-level groups. To improve insulation, abstraction, and compile-time perfor-
mance for our clients, we may choose to export only a subset of all headers needed to
compile a given package, group, or layer.

A patch is a local change to a previously released version of software. Making a patch

is typically less expensive and far less disruptive than re-releasing the entire system.
Our ability to patch a release is directly related to the degree to which implementation
details are insulated from clients. Types of changes that probably can and cannot be
realized with patches were presented in Section 7.6.2.

For a large software system written in C++, there is usually no "top"-no single pro-
gram that defines the system. The purpose of rna i n is only to provide a command-line
interface, interpret environment variables, and manage global resources.

Factoring the underlying functionality provided by rna i n into separately testable and
reusable components facilitates integration into yet larger subsystems. Only the . c
file rna i n can take unilateral global actions; components that do not define rna i n
should avoid egocentric behavior that might compromise the integration process down
the road.

Start-up is defined as the time from the moment a program is invoked until the thread
of control enters rna in. It is during this period that all non-local static objects defined
throughout the entire program are constructed. Naively ignoring the cost of such ini-
Section 7.9 Summary 549

tialization can result in unacceptably long invocation times. A module can be imple-
mented in C++ as a class containing only static members, and is preferable to a non-
local static instance, especially when the cost of initialization is high and the need for
the object is not immediate.

Four separate techniques for initializing static constructs were presented:

1. Wake up initialized: The static data member is of a fundamental type,

which can be initialized at load time.

2. Explicit i nit function: The i nit function for a component must be called
explicitly before the component can be used.

3. Nifty counter: A static instance of a dummy object defined in the header

file of the component guarantees intialization before use (at start-up).

4. Check every time: Initialization occurs on demand (Le., the first time any
function in the component is called).

The choice of initialization technique will depend on several factors, including:

• The "weight" of the component

• If and when the component is likely to be used
• The cost of initializing the component itself

Effective regression testing for memory leaks dictates that we provide a way to free
dynamic memory associated with static constructs--even if this feature is not
required by the application itself.
 PART III:
ALOE

Until now, the focus has been primarily on concepts that pertain to physical design
(e.g., components, levelization, insulation, and packages). Although good physical
design is critical to the success of larger projects, fundamental logical design issues
should be addressed by any project team early in the development process.

Logical design is a more mature and well-understood discipline than physical design.
Consequently, the presentation in this part takes on a different flavor. Where possible,
other readily accessibl~ books are cited to help minimize redundancy. Part III of this
book is a terse "reference manual" on the effective logical design of components.

Design patterns describe reusable micro-architectural units of cooperating compo-

.nents. There are countless design patterns in use in large software systems. This level
of logical design is, for the most part, beyond the scope of this book; however, many of
the most common design patterns are cataloged elsewhere and are readily accessible.

In this final part of the book, we limit ourselves to the design and implementation of
individual components. C++ provides an almost overwhelming logical design space.
This extra freedom can make finding an optimal design more complicated than is war-
ranted by the functionality implemented by the component. Our goal is therefore to
simplify the interface of each component and eliminate redundant degrees of freedom
that unnecessarily complicate the logical design space.
552 Logical Design Issues Part III

In Chapter 8 we take a high-level look at component design-this time from a logical

perspective. We consider the familiar concept of encapSUlation and characterize condi-
tions under which total encapsulation may be prohibitively expensive. We also identify
and contrast various ways in which to implement auxiliary objects used only within the
implementation of a component.

In Chapter 9 we focus our attention on the abundant issues that confront the compo-
nent-interface author as individual behaviors are cast into the syntax of C++ operators
and member functions. Whether to implement a particular behavior as a member or
free operator, whether to make it virtual, how to pass in a particular argument, and how
to return a value are just some of the 14 separate issues addressed. The consequences
of using the various flavors of integers (e.g., s h0 r t, un s i 9ned, 1 0 ng) in the interface
are also presented. We then take a close look at the issues surrounding special-case
functionality such as conversion operators, compiler-generated behaviors, and-in
particular-the destructor.

In Chapter lOwe tour some of the issues that face implementors of objects in a large-
system environment, with one eye toward performance and the other toward reliabil-
ity. Highlights include the selection and ordering of individual member data and the
effective implementation of individual functions. A large part of this chapter is
devoted to a quantitative analysis of the efficient customized management of an
object's memory. We see that object-specific memory management can be more effi-
cient than the conventional class-specific techniques, while avoiding the potential
problem of soaking up memory in long-running programs. Finally, we explore the
pitfalls of memory management in the context of generic, template-based container
classes and then briefly contrast the applicability of templates with design patterns.
 Architecting a Component

An individual object is usually too small to capture a complete concept. For an object to
be effective it may require free operators, or even entire friend classes, in order to cap-
ture the essential behavior of an abstraction. An abstraction is an abstract specification
of objects and functions that cooperate to serve some useful purpose. A component is a
concrete representation of that specification. A component is therefore also the funda-
mental building block of logical design.

Encapsulation, like insulation, can be a matter of degree. The costs associated with
complete encapsulation can often be prohibitively expensive. Sometimes we can
attain considerable performance gains without any real loss in flexibility by settling
for almost complete encapsulation. How and when to make this trade-off requires
careful deliberation.

A component will occasionally need to define and use in its implementation auxiliary
objects that are not intended for direct use by clients. C++ provides several techniques
for implementing such classes, each with advantages and disadvantages. There are
sound reasons for choosing exactly one of these approaches in most cases. Establish-
ing the selection criteria is all that is needed. In this chapter we consider several high-
level aspects of component interface design. We discuss the type and amount of func-
tionality that is appropriate for the component as a whole as well as for the individual
objects it contains. We characterize the costs associated with complete encapsulation,
and present ways to reduce that cost. Finally, we survey the many ways to implement
auxiliary objects within a component, and provide a rationale for making an imple-
mentation choice based on the properties emphasized by the particular usage model.
554 Architecting a Component Chapter8 .

8.1 Abstractions and Components

In Chapter 3 we introduced components as atomic units of physical design. Every..

thing placed in the header file of a component is made available at once. This physical
cohesion makes a component (not a class) the smallest unit of design that is indepen-
dently reusable across executable programs.

The component level is also the appropriate level for detailed logical interface design.
When you, as a user, take advantage of a component implementing, say, a list abstrac-
tion (see Figure 6-19) you are probably using more than the functionality provided in
the Lis t class itself. For example, writing a simple output statement such as

cout « "list = " « list « endl;

involves the use of a free operator (Le., operator «) that is not part of the logical
interface of any class. The Lis tIt e r class provides functionality, that is, an intrinsic
part of the list abstraction, yet this _functionality is not supplied by the interface of
class Lis t directly.

DEFINITION: An abstraction is an abstract specification of a collec-

tion of objects and related behaviors that fulfills a common purpose.

According to Stroustrup, l an appropriate definition of an abstract data type (ADD is a

formal abstract specification of a single object. A class (interface and implementation)
would then be a concrete specification of this object. By analogy, an abstraction is also
an abstract specification, with a component being the analogous concrete specification.

A class is a concrete specification of an ADT; a component is a con-

crete specification of an abstraction.

1 stroustrup, Section 1.2.3, pp. 18-19.

section 8.2 Component Interface Design 555

In other words, a component is the realization of not just a type, but of a self-consistent
microcosm of functionality that, taken as a whole, comprises what we call an abstrac-
tion. It is the entire abstraction, not just a single ADT, that defines a useful logical par-
tition of the functionality within a system that is implemented by a component.

8.2 Component Interface Design

There are several aspects to the quality of a well-designed component interface. 2 At a

minimum, the interface must be sufficient for intended clients to make efficient use of
the abstraction that the component was designed to support. Consider a component
implementing a set abstraction. The ability to

1. determine membership in the set,

2. - iterate over the members of the set, or
3. remove a given member from the set

mayor may not be necessary for any particular client. However, without the addi-
tional ability to add members to the set, this component will be of little use to anyone.

• Private interfaces should be sufficient.

• Public interfaces should be complete.
• Class interfaces should be primitive.
• Component interfaces should be minimal yet usable.

2 booch, Section 3.6, p. 136.

556 Architecting a Component Chapter 8

If a component is not intended for public use, then, as suggested in Section 1.8, the
minimal subset of functionality that does the job efficiently for its known fixed set of
clients is, by definition, sufficient. At the other end of the spectrum, if a component is
intended to be reused widely in various situations throughout a system, then we can-
not necessarily know ahead of time what subset of the functionality will be needed. 3
A complete interface enables all operations commonly expected by users of a given
abstraction to be accomplished in an efficient manner. The more remote our clients,
the more likely we are to opt to err on the side of generality by trying to make the
interface complete. 4

Where practical, deferring the implementation of unneeded

functionality reduces the cost of development and maintenance, and
avoids prematurely committing to a precise interface or behavior.

Often a complete interface requires a more involved implementation strategy than one
that would be sufficient for any individual client. Hence, a complete interface may be
more expensive to implement. The more general implementation may also run more
slowly than a specialized version, perhaps even on the most basic and frequently used
operations. 5 Hence, a complete interface may be more expensive at runtime. A more
complete interface is usually larger and more complex, incorporating less frequently
used features. A larger or more complex interface makes it more difficult for clients to
find and use basic features. Hence, a complete interface may be more expensive to
use. Since a complete interface is more expensive according to a variety of measures,
it is wise to be sure that a complete interface is warranted before implementing one.

3 Accidental reuse implies use in situations other than for which a component was originally
intended. Intentional reuse implies (among other things) a desire on the part of the component
author to provide a complete interface and a robust implementation. If you were to link to a com-
ponent that is part of a standard library of "reusable" components (e.g., STL), would you be using it
or reusing it? What about; ostream? .
4 See meyers, Item 18, p. 62.
5 For example, template-based container classes that must work correctly when parameterized by
arbitrary user-defined types cannot take the same liberties with bit-wise copy routines (such as
memcopy) as could a container designed exclusively for fundamental types (see Section 10.4.2).
Section 8.2 Component Interface Design 557

Between the two extremes of sufficient and complete can lie a wide middle ground.
For example, it is generally true that assigning the state of one iterator to that of
another is almost never performed in practice. Hence, an iterator's assignment opera-
tor can usually be declared private and left unimplemented, without affecting the
usability of the component. This deliberate omission saves development time and
code size, yet leaves open the possibility of adding that functionality without causing
existing clients to rework their code.

DEFINITION: An operation defined on an object is primitive if

implementing that operation efficiently implies having direct access
to private details of the object.

When selecting functions for the interface of a class, our goal should be to strive for a
minimum set, using primitiveness as a criteria. Clearly, adding and deleting members
of a set are independent primitive operations. The ability to iterate over the members
of a set enables a client to determine membership, suggesting that membership itself
is not an independent primitive operation. However, it is likely that determining mem-
bership via iteration is fundamentally much less efficient than it would be if imple-
mented with direct private access to the internal representation (e.g., by binary
search). If determining membership is likely to be a frequently used operation, it
would almost certainly qualify for primitive status.

Even a potentially significant performance benefit is a legitimate reason to treat an

operation as primitive. Consider the St r i n9 class of Figure 6-9. We are not sure
whether we are going to have a d_l ength member in the class or not. If we do, then
we will surely want to provide a primitive 1 ength ( ) accessor function. If we decide
against, then we will simply have 1 ength ( ) forward its call to the standard C library
function strl en(const char *) along with the underlying representation. In the
latter case, there is no actual performance gain; however, unless we provide the
1eng t h ( ) member, there is no way to give clients the maximum benefit afforded by
each implementation as we experiment back and forth between the two. Whether or
not we have a d_ 1eng t h member should in no way force clients to rework their code;
such considerations are part of the subtle art of encapsulation.
558 Architecting a Component Chapter 8

" ... p•. . . . • . . . ~ ·~············I·· "'i/l~

I.<••.•.••.•••••••.•.•••.•.•.·•.. ~~~lc:~I···.·. ·~·.·.·.!I •.

Keeping the functionality to a practical minimum enhances both

usability and reusability.

When selecting functions for the interface of a component, our goal is again to strive for
minimality, but with an eye toward usability. Supplying every conceivable operation for
an abstraction in a component interface increases its girth, overwhelms its clients, and
adversely effects its usability. For example, we could provide non-primitive support for
replacing the top entry on the St a c k of Figure 3-2. Although potentially useful to a few
clients, most would find such functionality superfluous.

By the same argument, we could also have omitted the tests for equality in the stack
component of Figure 3-2. Since these tests are implemented as free, non-friend func-
tions, operator== and operator!= could instead be implemented by any developer
who needs them. But if many users are developing applications that will work
together in a large system, it is desirable to avoid having each user rewrite the same
functions within each subsystem. Such redundancy wastes development time, execut-
able size, and, consequently, execution time. Finding the appropriate non-primitive
functionality to add to a component to make it most useful is a design goal. Often the
smallest interface that accomplishes this goal is optimal.

Minimizing the use of externally defined types in a component's

interface facilitates reuse in a wider variety of contexts.

The term coupling applies to both logical and physical designs. Physical coupling
comes from placing logical entities in the same component or by creating a physical
dependency of one component upon another. Logical coupling arises from types used
in the interface of one component that are defined or supplied by other components.
Section 8.2 Component Interface Design 559

As with physical coupling, logical coupling is best kept to a minimum. Reducing the
number of external types used in the logical interface often makes a component easier
to use and to maintain.

Suppose you are creating a very public interface and you need to accept character
string inputs. Which interface in Figure 8-1 do you feel is more general? Your clients
may have their own string class which they are accustom to using. Every general-pur-
pose string class will know how to generate a canst cha r * representation. The inter-
face of Figure 8-1a will force your clients to use class my_St ri ng; the interface of
Figure 8-1 b will not.

II my_engine.h II my_engine.h
#ifndef INCLUDED_MY_ENGINE #ifndef INCLUDED_MY_ENGINE
#define INCLUDED_MY_ENGINE #define INCLUDED_MY~ENGINE
class my_String; my_Engine {
I I ...
my_Engine { public:
I / ... . my_Engine(canst char *name);
public: // ...
mY_EngineCconst my_String& name); void setNameCconst char *name);
/ I ... / I ...
void setName(canst my_String& name); canst char *nameC) canst;
// ... // ...
canst my_String& name() canst: };
// ...
}; #endif

#endif

(a) Using my _St ri ng in the Interface (b) Using cons t cha r * in the Interface

Figure 8-1: Avoiding Logical Coupling

The consequences of this form of logical coupling would have been even more severe
had we instead elected to depend on some other non-standard component-library type
(e.g., yaur_Stri ng in the interface). Until an ANSIIISO standard string component
560 Architecting a Component Chapter 8

is universally available, there will continue to be an advantage to preferring canst

cha r * over any other string representation in a ubiquitious interface.

In short, there are a number of high-level questions we must ask ourselves when
designing the interface of a component. The most important questions is, "How public
is this component?" If it will be reused in lots of different and unpredictable ways, it
will need to have a reasonably complete interface. If the component is intended for
private use within a package (and will not be exported), the interface should be suffi-
cient-nothing more. In all cases we can improve the maintainability of our classes if
we design their interfaces to contain only primitive functionality, pushing off useful
but non-primitive functionality into separate operators or classes without private
access. Finally, logical coupling often can result in unwanted physical coupling;
avoiding the use of unnecessary types in the interface of a component that are defined
outside that component can help to alleviate this coupling.

8.3 Degrees of Encapsulation

Encapsulation can be harder to achieve than it might at first seem. Like total insula-
tion, total encapsulation can also be prohibitively expensive at runtime.

Figure 8-2 is an example of poor encapsulation. 6 Instead of taking an argument, each

manipulator function returns a writable reference to a private data member.

II bad_point.h
#ifndef INCLUDED_BAD_POINT
#define INCLUDED_BAD_POINT

class bad_Point {
int d_x; // (may change to short later)
int d-y; 1/ (may change to short later)

public:
II CREATORS
ba d_P 0 i nt ( i nt x. i nt y) : d_x Cx ), d3 Cy) {}
bad_Point(const bad_Point& p) : d_x(p.d_x), d-yCp.d-y) {}

II MANIPULATORS
bad_Point& operator=(const bad_Point& p) {
d_x = p.xC); d-y = p.y(); return *this; }
i nt & xC) { ret urn d_x;} I I bad ide a
i nt & y () { ret urn d-y;} I / bad ide a

6 See meyers, Item 30, pp. 100-102.

section 8.3 Degrees of Encapsulation 561

II ACCESSORS
int xC) const { return d_x; }
int y() const { return d-y; }
};

#endif

Figure 8-2: Example of Poor Encapsulation

Figure 8-3 shows a trivial test driver for the bad_Poi nt interface.

II bad_point.t.c
#include "bad_point.h"
#include <iostream.h>

ostream& operator«(ostrearn& a, conit bad_Point& p)

{
return 0 « 'c' « p.xC) « ", " « p.y() « ')';
}

rna i n ( )
{
bad_Point ptCl,2);
cout « pt « endl;
pt.xC) = 5;
cout « pt « endl;
}

Figure 8-3: Test Driver for Poor bad_Poi nt Interface

When run on the example as shown in Figure 8-2, this driver produces the following
output (as expected):

john@john: a.out
( 1, 2)
C 5, 2)
john@john:

But now suppose we change the type of the private data members in bad_Poi nt from
i n t to s h0 r t:

class bad_Point {
short d_x; II OK, we changed "private" data
short d-y; II so what?

public:
I I ...
562 Architecting a Component ChapterS

and rerun the experiment. The results have now changed to the unexpected:

john@john: a.out
( 1, 2)
( 1, 2)
john@john:

The problem is that the reference returned in the interface (i nt&) is inconsistent with
the type of data returned (s h0 rt). As a result, a temporary i ntis created and a writ-
able reference to that temporary is returned. We could modify the interface functions
to instead return ash 0 r t &, but then we would have modified the interface in response
to an implementation change-thereby propagating the problem to our clients.

A properly encapsulating version of the interface for ba d_Po i nt (like geom_Poi nt in

Figure 4-3) would define the manipulators to take the new value of the member to be
set as a parameter:

rna i n ( )
{
bad_Point pt(1,2);
cout « pt « endl;
Ilpt.x() = 5; II Returning writable reference replaced
pt.setX(5); II by function taking value of x coordinate.
cout « pt « endl;
}

The resulting output is again as expected-regardless of whether the data members

are declared i nt or s h0 r t :

john@john: a.out
( 1, 2)
( 5, 2)
john@john:

A good test for encapsulation is to see whether a given interface will

simultaneously support two significantly different implementation
strategies without modification.
section 8.3 Degrees of Encapsulation 563

In the b a d_P a i nt example, doing it right costs nothing extra; however, in some cases,
total encapsulation can be more expensive. Consider the two potential implementation
strategies for a geom_Box, shown in Figure 8-4. Implementation (a) stores the lower-
left and upper-right comers of the box as points embedded in the geam_Box. It is
therefore possible to return both the lower-left and upper-right comers by con s t ref-
erence. The center point is not stored, and so it must be calculated and returned by
value. Likewise, both the length and width must be calculated on demand. Implemen-
tation (b), however, stores the center point along with the width and height of the
geam_Box. The center point is returned efficiently by canst reference, while the
lower-left and upper-right comers must be calculated and returned by value. Length
and width now require no calculation, but-being fundamental types-they are
returned most efficiently by value.

class geom_Box { class geom_Box {

geom_Point d_lowerLeft; geom_Paint d_center;
geom_Point d_upperRight; int d_width;
int d_height;
public:
// ... public:
canst geam_Point& lawerLeftC) canst; // ...
const geam_Point& upperRight() canst; geom_Paint lowerLeft() canst;
geom_Paint center() canst; geom_Paint upperRight() canst;
int width() canst; canst geam_Point& center() canst;
int height() canst; i nt wi dth C) canst;
}; int height() canst;
};

(a) Stores Lower-Left and Upper-Right Comers (b) Stores Center, Width, and Height

Figure 8-4: Two Implementation Strategies for a geom_Box Class

Ilii::
-
i
~p¢iple>·'1 .................

A fully encapsulating interface may impose a significant performance

burden on a given implementation.

Part of the advantage of one implementation over the other is in avoiding the expense
of constructing the most frequently accessed point and instead returning it efficiently
by reference. Strictly speaking, however, these two interfaces, though similar, are not
564 Architecting a Component ChapterS

programmatically identical. For example, in implementation (b), it is possible to take

the address of the center point, while in implementation (a) it is not. Encapsulating
all aspects of the implementation would necessitate returning all three points (Le.,
from 1 owerLeft, center, and upperRi ght) by value, or passing in the address of a
previously constructed point whose value is to be assigned. In the case of geom_Box,
a fully encapsulating interface would eliminate much of the performance gain of one
implementation over another.

A classic example where encapSUlation is not complete can be found in virtually any
general-purpose string class, which for efficiency will invariably provide direct access
as a con s t c ha r * to its internal null-terminated string representation. Clearly this
interface constrains the internal implementation, forcing it to maintain a valid null-ter-
minated string representation as long as the string object is not modified or deleted.
However, a more encapsulating interface turns out to be too expensive or inconvenient
to be popular.

Another example where the interface constrains the implementation for efficiency can
be found in an unbounded array abstraction in which a writable reference to an
indexed object is returned. As illustrated in Figure 8-5a for an array of points, this
style of interface forces the implementation to maintain the same space for a
geom_Poi nt object once it has been referenced. Any attempt by the array to relocate
the object would invalidate references held by clients.

class geom_PointArray {
// ...
public:
// ...
geom_Point& operator[](int index);
const geom_Point& operator[](int index) canst;
// ...
};

Figure 8-5a: Partially EncapSUlating Interface (Array A)

By contrast, a naive, fully encapsulated version would provide functions to get and set
a particular element, as illustrated in Figure 8-5b. Notice that this interface is com-
pletely generaL There is nothing to stop us from storing the points internally as, say,
two parallel arrays of integers. We might decide to implement some kind of in-core
compression scheme for points. We might even think about swapping part of a large
array out to disk.
section 8.3 Degrees of Encapsulation 565

class geom_PointArray {
// ...
public:
// ...
geom_Point pointCint index) const;
void setPointCconst geom_Point& point, int index);
// ...
};

Figure 8-5b: Naive Fully Encapsulating Interface (Array B)

Passing in the address of a previously constructed object to be

assigned the return value (called return by argument) can improve
performance while preserving total encapsulation.

Although this new interface does nothing to limit our implementation choice, the
runtime cost of using this fully encapsulating interface could be substantially more
expensive--even when the two underlying implementations are identical. For less
lightweight elements (i.e., being significantly larger, having a non-inline copy con-
structor, or requiring dynamic memory allocation at construction), a fully encapsulat-
ing version of the interface could be prohibitively expensive at runtime.

Fortunately, there is another fully encapsulating form of the interface that does afford
some relief for "heavier" objects, particularly when accessing their values. Returning
an object by value will result in construction (and destruction) of at least one tempo-
rary of the indexed type. As Figure 8-5c illustrates, we can pass in a writable pointer
to an existing object instead of returning the object by value. Assigning the value of
the existing object Gust once) can often be accomplished with relative efficiency.

class geom_Po~ntArray {
// ...
public:
// ...
void getPointCgeom_Point *returnValue. int index) const;
void setPointCconst geom_Point& point. int index);
// ...
};

Figure 8-5c: Alternate Fully Encapsulating Interface (Array C)

566 Architecting a Component Chapters

To make this all concrete, I created a single experimental version of a Poi n tAr ray
class with all three modes of access available simultaneously. The contents of Figure
8-6 were placed at the top of a driver file used to compare the relative performance of
these three modes of operation.

/1 pointarray.t.c
#include "point.h"
#include <memory.h) // memcpy()

class PointArray {
Point **d_array_p; II array of pointers to Point objects
int d_size; // current physical size of "unbounded" array
Point d_dummy; // not static to avoid construction at startup

private:
void resize(int maxlndex); // extend array of Point pointers when needed

PointArray(const PointArray& array); // not implemented

PointArray& operator=(const PointArray& array); // not implemented

public:
// CREATORS
PointArray(int size) : d_array_p(O), d_size(O), d_dummy(O,O)
{
resize(size - 1); // Factoring 1S good.
}

. . . PointArray() ;

/1 MANIPULATORS
Point& operator[](int index) II ARRAY A
{
if (index )= d_size) {
resize (index);
}

void setPoint(const Point& point, int index) II ARRAY B &C

{
if (index )= d size) {
resize (index);
}

// ACCESSORS
int size() const {return d_size; } // ARRAY A, B, C
section 8.3 Degrees of Encapsulation 567

canst Paint& operator[](int index) canst II ARRAY A

{

Point paint(int index) canst II ARRAY B

{
return index )= d size? d_dummy *d_array_p[index]:
}

void getPoint(Point *returnValue. int index) canst II ARRAY C

{
*returnValue = index )= d_size ? d_dummy : *d_array_p[indexJ;
}
};

PointArray::-PointArray()
{
for (int i = D: i < d_size; ++i) {
delete d_array_p[i];
}
delete [] d_array_p;
}

void PointArray::resize(int maxlndex)

{
int newSize = maxIndex + 1;
Point **p = d_array_p;
d_array_p = new Point *[newSize];
memcpy (d_array_p, p. d_size * sizeof *p);
delete p;
for (int i = d_size; i < newSize; ++i) {
d_array_p[i] = new Point(D.D);
}
d size = newSize;
}

Figure'8-6: Experimental Po; ntArray Class Implementation

The first test was to compare the relative efficiency of reading the x coordinate of the
first 1,000 points of the array and accumulating this value in the variable sum. This
experiment was run for each of the three array interlaces as presented in Figure 8-7.
To illustrate the effect the "weight" of the object can have on the interlace, the three
different Poi nt implementations used in the experiment of Figure 6-83 were reused
here as well. 7

7 Data presented represents fully optimized code.

568 Architecting a Component Chapter 8

maine)
{
int arraySize = 1000;
int sum = 0;
PointArrayarray(arraySize);
canst PointArray& constArray - array; II Provide a const reference to
I I ... II enable the invocation of the
II canst version of operatar[]
II INTERFACE A:
{
for (int j = 0; J < arraySize; ++j) {
sum += canstArray[j].x();
}
}

II INTERFACE B:
{
for ( i nt J = 0; J < arraySize; ++j) {
sum += constArray.point(j).x();
}
}

II INTERFACE C:
{
Point ptCO,O);
for (int j = 0; j < arraySize; ++j)
canstArray.getPoint(&pt, j);
sum += pt. x ( ) ;
}

Figure 8-7: Experimental Poi ntAr ray "Reading" Driver

Figure 8-8 provides the results of comparing these three different interfaces styles for
accessing Poi nt objects within the same array. Using the original Poi nt class (line 1)
with all its functions declared inline, the cost of total encapsulation is only minimally
more for the naive encapsulation of ARRAY B (111 %) and nonexistent for the full
encapsulation of ARRAY C (100%). Removing the inline functions from the con-
tained Poi nt type (line 2) makes both constructing and assigning to Poi nt objects
somewhat more expensive. Part of the runtime advantage of ARRAY C (168%) over
ARRAY B (271 %) is that the Poi nt assignment is occurring exactly once per array
access without th~ extra constructor (and destructor) calls generally needed to return
an object by value. For a contained object that allocates dynamic memory on con-
struction (line 3), the cost of construction (1,673%) well exceeds the cost of assigning
the new value in place (169%). From this data we conclude that there can be substan-
Section 8.3 Degrees of Encapsulation 569

tial gains in performance for fully encapsulated classes if we return heavyweight

objects through the argument list instead of by value.

Partially Totally Also Totally

Encapsulating Encapsulating Encapsulating
ARRAY A ARRAYB ARRAYC
Line Description of Point Class

1. Original Point Class (light) 0.222 0.247 0.222

(100%) (111 %) (100%)

2. Without Inline Functions (medium) 0.296 0.802 0.497

(100%) (271%) (168%)

3. Fully Insulating Version (heavy) 0.369 6.173 0.622

(100%) (1,673%) (1690/0)

loop time in milliseconds on SUN SPARe 20

(time as percentage of Array A's time)

Figure 8-8: Relative Costs of Accessing a Po; ntArray Element

The second test was to compare the relative efficiency of setting the x coordinate of
the first 1,000 points of the array while leaving the y coordinate unchanged. Note that
interface A allows us to accomplish this operation directly, while interfaces B and C
force us to first get the current value of the entire point. This experiment, illustrated in
Figure 8-9, was also run for each of the three array interfaces and for each of the three
Poi nt implementations. The results are tabulated in Figure 8-10.

rna i n ( )
{
arraySize = 1000;
PointArrayarray(arraySize);
PointArray& nonConstArray = array; II provide non-canst reference.
I I ...

II INTERFACE A:
{
for (int j ~ 0; j < arraySize; ++j) {
nonCanstArray[j].setX(j);
}
}
570 Architecting a Component Chapter 8

II INTERFACE B:
{
for (int j = 0; j < arraySize; ++j) {
nonConstArray.setPoint(Point(j, nonConstArray.point(j).y(»), j):
}
}

II INTERFACE C:
{
Point pt(O,Q);
for (int j = 0; j < arraySize; ++j) {
nonConstArray.getPoint(&pt, j);
nonConstArray.setPoint(Point(j, pt.y(), j);
}
}
}

Figure 8-9: Experimental Poi ntAr ray "Writing" Driver

Partially Totally Also Totally

Encapsulating Encapsulating Encapsulating
ARRAY A ARRAY B ARRAY C
Line Description of Point Class

1. Original Point Class (light) 0.162 0.403 0.336

(100%) (249%) (226%)

2. Without Inline Functions (medium) 0.242 1.451 1.118

(100%) (503%) (418%)

3. Fully Insulating Version (heavy) 0.385 12.901 6.669

(100%) (3,551%) (1,732%)

loop time in milliseconds on SUN SPARe 20

(time as percentage of Array A's time)

Figure 8-10: Relative Costs of Manipulating a Po; ntArray Element

Based on the results of this experiment, we can conclude that providing a writable ref-
erence to the contained object can have profound performance benefits that increase
Section 8.3 Degrees of Encapsulation 571

dramatically with the weight of the object. For fully insulating classes, some degree of
relief is provided by returning the original value through the argument list.

Settling for less than full encapsulation is sometimes the right choice.

Fully encapsulating interfaces should be a design goal. However, if performance is

also a design goal, then extravagant implementation choices must be ruled out regard-
less of the degree of encapsulation. By making reasonable assumptions, we can
achieve superior performance while preserving the flexibility we need in order to
modify our implementation within appropriate limits.

As a final aside, we should note a subtle problem with the interface of the unencapsu-
lated version of this array. There are two versions of the [J operator:

aperator[](int index)

and

operator[](int index) canst.

The first of these operators can potentially resize the array; the second cannot. If this
array were implemented as a "sparse array," the space for a Poi nt (or a significan~ly
bigger object) might deliberately be left unallocated until referenced by the non-
eanst version of operator[]. With this interface, the act of merely "reading" a non-
e an s t array object will implicitly populate it. It would be far more practical to skip
the operator overloading and choose distinct function names for these operations.
Doing so would make this array far less prone to subtle misuse that could result in
grossly excessive allocations of memory.

To summarize: encapsulation is a cornerstone of good object-oriented design; its goal

is to minimize the logical dependency of clients on the details of an implementation
across an interface. More complete encapsulation affords implementors greater flexi-
bility in their choice of implementation. Yet, like insulation, total encapsulation for a
very low-level object can be prohibitively expensive at runtime.
572 Architecting a Component ChapterS

If perfonnance is a design goal, then certain implementation choices (e.g., object com-
pression and swapping to disk) must be ruled out anyway. By making reasonable
assumptions, learned through experience, we can attain most of the benefit of encapsula-
tion without incurring excessive and unnecessary runtime cost. When total encapSUlation
is appropriate, we can sometimes reduce its runtime cost by passing in a previously
constructed object to load instead of returning the object by value.

8.4 Auxiliary Implementation Classes

Often a component will make use of one or more tiny auxiliary classes in its imple-
mentation that are not programmatically accessible in the interfaces of the principal
classes defined in that component. Two characteristics help to distinguish an auxiliary
implementation class from other kinds of classes:

1. The class is intended for the sole purpose of implementing a component

and is not intended for direct use (or reuse) outside that component.

2. The class is trivial and may not warrant direct testing.

The Lin k class of the list component shown in Figure 6-19 is a case in point. There
are a variety of ways to realize such implementation classes, each with its advantages
and disadvantages. In this section we explore the pros and cons of a variety of design
options.
Section 8.4 Auxiliary Implementation Classes 573

Consider a simple integer list class shown in Figure 8-11a. Class my ~L ink is an imple-
mentation detail of my _L i s t, and is not programmatically accessible from my _L i st. In
this implementation, the auxiliary class definition is placed in the header file of the
component defining the primary class. This straightforward approach is the simplest
and most common method of implementing components using such auxiliary classes.

II my_list.h
#ifndef INCLUDED_MY_LIST
#define INCLUDED_MY_LIST

class my_Link {
int d_data;
my_Link *d_next_p;

public:
I I ...
};

class my_List {
my_Link *d_head_p;
I I ...
public:
II
};
my_list
#endif

Figure 8-11a: (Original) File Scope Implementation of my_L ink (A)

574 Architecting a Component Chapter 8

We could put the link class in its own component, as illustrated in Figure 8-11 b. This
arrangement has the advantage of allowing us to test (and even reuse) my_L ink inde-
pendently of my _L i st. But for tiny implementation classes such as my _L ink, the cou-
pling brought about by reuse along with the extra physical complexity of a second
component makes this an unlikely choice.

II my_list.h
#ifndef INCLUDED_MY_LIST
#define INCLUDED_MY_LIST

class my_Link;

class my_List {
my_Link *d_head_p;
I I ...
public:
II
};
II my_link.h
1fendif #ifndef INCLUDED_MY_LINK
#define INCLUDED_MY_LINK 1
c 1 ass my _ Lin k {
int d_data;
my_Link *d_next_p;
my_link
public:
II
};

1Iendif

Figure 8-11b: Separate Component Implementation of my _L ink (B)

We could declare my _L i s t a f r i end of class my _L ink and make all of the link's func-
tions private, as suggested in Figure 8-11c. Making my _L ink a "slave" class of
my _L i s t prevents clients of component my _1 i s t from using my _L ink directly; how-
ever, access for direct testing is also precluded.
section 8.4 Auxiliary Implementation Classes 575

II my_list.h
#ifndef INCLUOED_MY_LIST
#define INCLUDED_MY_LIST

class my_List;

class my_Link {
int d_data;
my_Link *d_next_p;
friend my_List;
I I ...
};

class my_List {
my_Link *d_head_p;
I I ...
public:
II
}; my_list
#endif

Figure 8-11c: Slave Class Implementation of my _L ink (C)

We could make the my _L ink class a local definition, contained entirely within the . c
file, as illustrated in Figure 8-11d. This design would serve to insulate clients from
my _ Lin k. However, in addition to precluding direct testing, this design would also
preclude inlining any members of my _L i s t that made substantive use of my _L ink. If
component my _, i s t had also contained an iterator, not being able to inline iterator
functions might have significantly degraded runtime performance.

II my_list.h
#ifndef INCLUDED_MY_LIST my_list
#define INCLUDED - MY - LIST

class mY_Link;

class my_List {
my_Link *d_head_p;
// ...
public:
II
}:
my_I ist. h my_list.c
#endif

Figure 8·11d: Local Class Implementation of my _L ink (D)

576 Architecting a Component ChapterS

Finally, we could make the my _ Lin k class a private (or public) nested class whose def-
inition is contained entirely within class my _L i s t, as illustrated in Figure 8-11e. This
implementation would not insulate clients from the details of my _L ink, but it would
permit members of my _ Lin k to be used in the bodies of inline members of my _ Lis t
(and my _ Lis tIt e r ). Making my _ Lin k a nested class avoids affecting the global name
space; making it private makes it encapsulated and therefore not directly usable (or
testable).

II my_list.h
#ifndef INCLUDED~MY_LIST
#define INCLUDED_MY_LIST

class my~List {
class my_Link {
int d_data;
my_Link *d~next~p;

public:
I / ...
};

my_Link *d_head_p;
/ I ...
public:
I / ...
}; my_list

Figure 8-11e: Nested Class Implementation of my _L ink (E)

The advantages of each of the implementation alternatives for the my _L ink class pre-
sented in this section are summarized in Figure 8-12. Placing my _ Lin k in a separate
component (implementation B) is clearly the most flexible, allowing the component
author to include the auxiliary class definition in either the . c file or the . h file of the
principal component as needed. However, there is a cost associated with each physical
piece of a system. Unless we plan to directly test or independently reuse the auxiliary
class, creating a separate component to hold it would probably be unwarranted.

Nested classes are not as flexible as classes defined at file scope. For example, nested
classes cannot be forward declared;8 hence, nested classes cannot be insulated from
clients of their enclosing class. In addition, nested types are notationally cumbersome

8 The ANSIIISO committee has adopted a proposal to allow the forward declaration of nested
classes in c++. See stroDstrup94, Section 13.5, pp. 289-290.
Section 8.4 Auxiliary Implementation Classes 577

and cause excessive clutter in the physical interface. The syntax of the nested imple-
mentation inhibits our conveniently transplanting the auxiliary class to the . c file or to
another component, should we later decide to insulate or reuse it.

Is Directly Testable

Affects Global Name Space

Can Be Used in Inline Bodies

Is Physically Coupled

Can Be Insulated

Is Reusable

(A) File Scope (Original) YES YES YES YES NO NO

(B) Separate Component YES YES YES NO YES YES

(C) Slave Class NO YES YES YES NO NO

(D) Local Class NO NO* NO YES YES NO

(E) Nested (Private) Class NO YES YES YES NO NO

(E') Nested (Public) Class YES NO YES YES NO NO

*Presumes class does not involve constructs with extemallinkage.

Figure 8-12: Summary of Various Auxiliary Class Implementation Advantages

The original implementation (A) and the public nested implementation (E') have sim-
ilar properties. The one benefit of the nested public design is that it does not affect the
global name space. Considering the disadvantages of nested classes described aboye,
if you're going to make a nested class public, why not just prefix its name and define
it at file scope in the . h file (as in implementation A)?
578 Architecting a Component Chapter 8

Though not insulated, private nested classes are truly encapsulated and cannot be
accessed by clients of the primary objects, nor can they be directly tested. The slave
class implementation (C) is almost identical to the private nested class implementa-
tion (E), except that the class itself is part of the global name space, though still not
usable or testable directly. The local class implementation (D) is also similar to a pri-
vate nested implementation (E), except that the local classes are insulated from clients
and therefore cannot be used in the bodies of inline functions of the primary classes.
For more on classes without extemallinkage, see Section 3.2 (immediately following
the discussion of Figure 3-7).

The best choice in any given situation will depend on the answers to the following
three questions:

x. Does the auxiliary component warrant direct testing?

In our 1 i s t component, the Lin k class will automatically be tested with

100 percent coverage just by testing the Lis t class under normal condi-
tions; there is no practical advantage to testing Lin k directly. In cases
where the auxiliary class is more complex, we should probably allow for
direct access, which would eliminate slave (C), local (D), or private
nested (E) auxiliary class implementations.

y. Does the component expose inline functions that require access to the
auxiliary class? .

If the component's header does not define inline functions that make sub-
stantive use of an auxiliary class, that class can be insulated from clients
and is often best implemented locally (D). However, if the auxiliary class
is complex enough to warrant direct testing, the class should be imple-
mented using either (A) or (B).

z. Will the component be used widely?

If the component is used only in the implementation of a single sub-

system, then there may be no need to get fancy. The original implementa-
tion (A) will often be a good choice.
Section 8.5 Summary 579

A decision tree to aid in making the decision is provided in Figure 8-13.

(x?)
x. Does the auxiliary
/~
class require direct no yes
testing? / ~
(y?) (y?)
y. Do inline functions /~ /~
need access to the no yes no yes
auxiliary class?
(z?) (z?) (z?) (z?)
z. Will the component /\
no yes
/\
no yes I""
no yes I"'"
no yes
be used widely?
D D A C/E A B A B*
*The header for the auxiliary class is included in the. h file instead of the . C file
of the principal component.

Figure 8-13: Deciding Which Auxiliary Class Implementation to Use

To sum up: defining auxiliary classes in the same header file as the primary classes is
common; often this approach is adequate, if not optimal. Where possible, we would
like to insulate auxiliary classes from our clients by hiding them in the . c file or, if
necessary for testing, placing them in a separate component. For lightweight compo-
nents that are widely used, we may be forced to use slave or private nested classes to
enforce our sole ownership of the auxiliary class. This section is intended as a guide-
line and is not a substitute for the application of common sense.

8.5 Summary

Components serve jointly as effective units of both logical and physical design. An
abstraction is an abstract specification of closely related objects and (operator) func-
tions; a component (interface and implementation) is the corresponding concrete
realization.

There are several competing aspects to consider when creating the high-level specifi-
cation for a component. For components designed as part of a specific subsystem, we
require only that the interface be sufficient for its intended clients. For components that
will be used for various purposes throughout a large system, we expect the interfaces
580 Architecting a Component Chapter 8

to be complete. By sufficient we imply that the interface is suitable for solving a par-
ticular instance of a problem in some domain. By complete we mean that the interface
is suitable for solving an arbitrary problem in that domain. Both usability and main-
tainability are enhanced by keeping all component interfaces minimal.

Operations defined as members of individual objects should be primitive. An operation

is primitive if its efficient implementation requires direct access to private details of the
class. Operations that are useful but not primitive should be implemented outside of
the object in terms of primitive functions, and should not be granted friend status.

User-defined types used in the interface of a component imply a strong logical depen-
dency on that type. As with physical coupling, logical coupling is best minimized. For
example, it is often preferable to use a canst cha r * parameter instead of some par-
ticular string class in order to avoid unnecessary logical coupling, especially if the
interface will be used by a variety of clients in many different contexts.

Encapsulation is a property of an object that enables the implementation of that object

to be modified without affecting its logical interface. Sometimes total encapsulation
can be prohibitively expensive. However, encapsulation, like insulation, need not be
absolute in order to be useful. Often we can make reasonable assumptions that allow
us to achieve our performance goals, and still preserve sufficient encapsulation to
allow us to continue to modify the implementation within reasonable limits. If total
encapsulation is required, we can sometimes achieve a sizable performance gain by
passing in a previously constructed object as a writable argument to be loaded with
the result, rather than returning the result by value. The performance gain for return
by argument over return by value is even more pronounced for heavyweight objects
that manage internal dynamic memory.

When implementing a component, there is often a need to create one or more auxil-
iary classes. These classes are not accessible through the interface(s) of the primary
object(s) defined in the component. These classes are implementation details of the
component and are simple enough that they may not require independent testing. The
following strategies have been identified for implementing auxiliary classes:

• At file scope in the. h file.

• In a separate component.
• As a slave class of one or more primary classes.
• In the . c file of the component.
Section 8.5 Summary 581

• As a private (or public) nested class of a primary class.

Figure 8-12 identifies the various advantages of these implementation strategies for
auxiliary classes with respect to the following questions:

• Is the auxiliary class directly testable?

• Does the auxiliary class affect the global name space?
• Can the auxiliary class be used in inline function bodies?
• Is the auxiliary class physically coupled?
• Can the auxiliary class be insulated from clients?
• Is the auxiliary class independently reusable?

Figure 8-13 provides a decision tree that can be used to select the appropriate imple-
mentation for an auxiliary class based on the context in which it will be used.
 Designing a Function

The goal of function design is to provide safe, easy, and efficient access to the behav-
iors defined by an abstraction. The C++ language provides great latitude when it
comes to specifying the interface at the function level. Whether to make a function an
operator, whether it should be a member or free operator, how arguments should be
passed, and how values should be returned are all part of this level of the design pro-
cess. There are reasons beyond style that playa role in making these design decisions,
many of which we touch on in this chapter.

The C++ language places a variety of flavors of fundamental integer types (such as
s h0 r t, un s i 9 ne"d, 10 n g, etc.) at our disposal. These types represent yet another degree
of freedom that, if used thoughtlessly, can complicate and even weaken an interface.

A user-defined conversion operator allows the compiler to convert implicitly to or

from a user-defined type. Careful design requires weighing the possible advantages of
implicit conversion against ambiguities and potential for errors caused by the result-
ing degradation in type safety. Certain other functions, if not explicitly specified, will
be defined automatically by the compiler if needed. Deciding when these compiler-
generated function definitions are good enough requires thoughtful consideration.

In this chapter we provide a framework in which to design the interface of a compo-

nent, but at the level of detail of an individual function. We examine the excessively
large design space available to component authors and identify design decisions that
have shown themselves to be either beneficial or counter productive. We see how
many unnecessary degrees of freedom in the design" space of the functional interface
584 Designing a Function Chapter 9

can be eliminated without any loss in effectiveness. The resulting framework can then
help guide us toward simpler, more uniform, and more maintainable interfaces.

9.1 Function Interface Specification

There is a list of issues one must address when specifying the interface of a function
in C++ in accordance with the ground rules presented in Chapter 2:

1. Operator or non-operator function?

2. Free or member operator?
3. Virtual or non-virtual function?
4. Pure or non-pure virtual member function?
5. Static or non-static member function?
6. canst or non-canst member function?
7. Public, protected, or private member function?
8. Return by value, reference, or pointer?
9. Return canst or non-canst?
10. Argument is optional or required?
11. Pass argument by value, reference, or pointer?
12. Pass argument as canst or non-canst?

There are two organizational issues that, although not part of the logical interface,
must also be addressed:

13. Friend or non-friend function?

14. Inline or non-inline function?

There is a great deal of interplay among these issues; typically the answer to one
question will imply or at least affect the answer to another. In what follows we
address each of these issues individually, and provide guidelines for making optimal
design decisions. l

9.1.1 Operator or Non-Operator Function

Apart from the compiler-generated operators (e.g., assignment), the only reason to
make a function an operator is for the notational convenience of the client. Note that,

1 See also meyers, Item 19, p. 70.

Section 9.1.1 Operator or Non-Operator Function 585

unlike function notation, operator notation is not context sensitive; the resulting func-
tion call resolution of an operator invoked from a member function will be the same
as if invoked at file scope. 2 When used judiciously, operator overloading has a natural
and obvious advantage over the functional notation-especially for user-defined logi-
cal and arithmetic types.

#include "pub_intset.h" #include "pub_intset.h"

#include <iostream.h> #include <iostream.h>

rna i n ( ) rna i n ( )
{ {
pUb_IntSet a, b, c, d, e, f; pub_IntSet a, b, c, d, e, f;

a += 1; a += 3; a += 5; a += 7; a.add(l); a.add(3); a.add(5); a.add(7);

b += 1; b += 2; b += 3; b += 4; b.add(l); b.add(2); b.add(3); b.add(4);
c = a + b; d = a*b; e = a - b; c = pub_IntSet::or(a, b);
d = pub_IntSet::and(a, b);
e = pub_IntSet::sub(a, b);
f = a*b*c + b*c*d + c*d*e; f = pub_IntSet::or(
pub_IntSet: :or(
pub_IntSet::and(
pub_IntSet: :and(a, b),
c
),
pub_IntSet: :and(
pub_IntSet::and(b, c),
d
)
),
pub_IntSet::and(
pub_IntSet: :and(c, d),
e
)
);

cout « f « endl; pub_IntSet: :print(cout, f) « endl;

} }

(a) With Operator Overloading (b) \Vithout Operator Overloading

Figure 9-1: 1\vo Usage Models for an Integer Set Abstraction

Consider the two different usage models shown in Figure 9-1, corresponding to two
different interfaces for an integer set component, pUb_intset. Figure 9-1a illustrates
how operator notation can be used effectively. The nature of the set abstraction makes

2 eUis, Section 13.4.1, p. 332.

586 Designing a Function Chapter 9

the meanings of these operators intuitive, even for developers not familiar with this
particular component. Figure 9-1 b shows the equivalent computation using the more
bulky function call notation. 3

Readability (more than ease of use) should be the primary reason for
employing operator overloading.

In this integer set application, the operator notation clearly enhances both readability
and ease of use. By readability, we mean the ability of a software engineer to discern,
quickly and accurately, the intended behavior of a body of unfamiliar source code.
Ease of use refers to how easily a developer can use the object effectively to create
new software. Any typical body of source code is read many more times than it is
written ("For most large, long-lifetime software systems maintenance costs exceed
development costs by factors ranging from 2 to 4,,4), so it makes practical sense to
favor readability over ease of use in the long run.

Guideline
The semantics of an overloaded operator should be natural, obvious,
and intuitive to clients.

It is easy to come up with cute and easy-to-use applications for operators that have no
intuitive meaning for developers unfamiliar with your component. Sophomoric antics,
such as defining unary ope r a to r"'" as a member of a string class to reverse the string in
place, are obviously out of place in a large-scale development environment. The lit-
mus test for determining when to supply operator notation should be whether there is

3 We have made some of the member functions static to enable the same symmetric implicit conver-
sion of arguments, as do the corresponding operators (see Section 9.1.5). The indentation style of
the deeply nested function calls in Figure 9-1 b is borrowed from languages such as LISP and CLOS
where such constructs occur frequently_
4 sommerville, Section 1.2.1, p. 10.
Section 9.1.1 Operator or Non-Operator Function 587

a natural and intuitive meaning-immediately obvious to new clients-that improves

(or at the very least maintains) the level of readability.5

Guideline
The syntactic properties of overloaded operators for user-defined types
should mirror the properties already defined for the fundamental types.

At a semantic level, it is quite difficult to provide specific guidelines as to what is and

what is not intuitive. However, at a syntactic level we can make a number of strong
and well-defined statements based on the implementation of the fundamental types in
the language.

Patterning the syntactic properties of user-defined operators after

the predefined C++ operators avoids surprises and makes their usage
more predictable.

In the C++ language, every expression has a value. There are two basic types of values,
called lvalues and rvalues. 6 An lvalue is a value whose address can be taken. If an
lvalue can be on the "left" of an assignment statement, it is said to be a modifiable
lvalue; otherwise it is said to be a non-modifiable Ivalue. 7 An rvalue cannot be
assigned to nor can its address be taken. 8 The simplest lvalued expression is a variable
identifier itself. Unless the variable is declared con s t, it is a modifiable Ivalue.

5 See also cargill, Chapter 5, p. 91.

6 Originally these terms came from classic C: the term lvalue meant that the value of an expression
could appear on the left of an assignment statement while an rvalue could appear only on the right.
With the advent of canst in C++ and ANSI C, lvalues are now divided into two flavors: modifiable
and non-modifiable (see stroostrop, Section 2.1.2, p. 46--47).
7 ellis, Section 3.7, p. 25-26.
8 Bit fields are an exception in that they can appear on the left of an assignment statement, yet
according to the ARM (ellis, Section 9.6, p. 184), the address of a bit field may not be taken. The
same is true for unnamed temporaries of a user-defined type (see Section 9.1.2).
588 Designing a Function Chapter 9

Certain operators, such as assignment (=) and its variations (+= -= *= /= "= &= 1=
~= %= »= «=), pre-increment (++x), and pre-decrement (--x) all return modifiable
lvalues when applied to fundamental types. These operators always return a writable
reference to the modified argument. For example the hypothetical definition of these
operators for the fundamental type do Ub1e (if implemented as a C++ class) might
look as shown in Figure 9-2.

class double { II Note: not legal C++

I I ...
public:
double() {}
double(int);
double(const double&);
,....d 0 ub 1 e () {}

double& operator=(const double& d);

double& operator+=(const double& d);
double& operator-=(const double& d);
double& operator*=(const double& d);
double& operator/=(const double& d):
double& operator++(); II pre-increment ++x
double& operator++(); II pre-decrement --x
double operator++(int); II post-increment x++
double operator--(int); II post-decrement x--
double *operator&(); II unary address operator
canst double *operator&() const ; I I unary address operator
};

double operator+(const double& d); II unary +

double operator-(const double& d); II unary -

int aperatar!(const double& d); II unary logical "natl!

int aperator&&(const double& left, const double& right);
int operatorll (canst double& left, canst double& right);
double operator+(const double& left, canst double& right);
double operator-(const double& left, canst double& right);
double operator*(const double& left, canst double& right);
double operator/(const double& left, canst double& right);
int operator==(const double& left, const double& right);
int operator!=(const double& left, const double& right);
int operator< (const double& left. const double& right);
int operator<=(const double& left, -const double& right);
int operator> (const double& left, const double& right);
int operator>=(const double& left. const double&-right);

Figure 9-2: Hypothetical Implementation of Fundamental Type do U b1 e

Section 9.1.1 Operator or Non-Operator Function 589

Other operators shown in Figure 9-2 return an rvalue because there is no appropriate
Ivalue to return. In the case of symmetric binary operators (such as + and *), the value to
be returned is neither the left argument nor the right argument but a new value derived
from both; consequently the return must be by value. 9 Equality (== !=) and relational
« <= > >=) operators always return an i nt type rvalue of either 0 or 1; clearly neither
of the input arguments would be appropriate to return here either. The post-increment
and post-decrement operators are an interesting special case in that they are the only
operators that modify the object and yet have no appropriate lvalue to return:

double double::operator++(int) double double::operator--(int)

{ {
double tmp = *this; double tmp = *this;
++*this; --*this;
return tmp; return tmp:
} }

As a more subtle example, consider the two usage models corresponding to a generic
symbol table abstraction shown in Figure 9-3. In both cases, a symbol table-parame-
terized by type i nt-is constructed, two symbols are added, and the value of symbol
"foo" is looked up by name. Since it is entirely possible that a symbol with the speci-
fied name does not exist in the table, it is not appropriate for the function doing the
lookup to return its result by value or reference; hence the value is returned by pointer.
(Notice how and to what degree we have just taken liberty with encapsulation.) But
compare this usage with what we normally expect when we apply 0 per at 0 r [] to a
fundamental array of i nt. We expect to get back a reference to the indexed value, not
a pointer which may be null. This difference in usage between the 0 per at 0 r [] in Fig-
ure 9-3a and the usage of operator[] for fundamental types tends to make the func-
tion call notation of Figure 9-3b preferable in this case. Reserving the operator
notation for those cases where the syntax closely mirrors the corresponding funda-
mental syntax reinforces the effectiveness of operator overloading.

9 For a more detailed explanation, see meyers, Item 23, pp. 82-84.
590 Designing a Function Chapter 9

#include "gen_symtab.h" #include "gen_symtab.h"

maine) maine)
{ {
gen_SymTab<int> s; gen_SymTab<int> s;
s("foo", 1); II operator() s.add("foo", 1);
s("bar", 2); II (bad idea) s.add("bar", 2):
const int *val = s["foo"]; const int *val = s.lookup("foo");
I I ... I I ...

(a) With Operator Overloading (b) Without Operator Overloading

Figure 9-3: Two Usage Models for a Generic Symbol Table Abstraction

Figure 9-4 summarizes the declarations of most C++ operators as they would be if
applied to fundamental types. (The fundamental operators - > ->* () and , provide
little insight.)

II operators with similar declarations

class T {
T& operator++(); II ++x --x (prefix)
T operator++(int); II x++ x-- (postfix)
T* operator&(); II &x (unary)
const T* operator&() const; II &x (unary)

T& operator=(const T&): II = += -= *= 1= %= «= »= &= A= 1=

}:

T operator-(const T&); II - + ,. . (unary)

int operator!(const T&); II (unary)

T operator+(const T&, const T&); II + - * I « » % & A

1
int operator==(const T&, const T&): II -- .1= < <= > > =
int operator&&(const T&, const T&); II && 1 1
II if the type is. pointer-like (i .e., P = T*)

class P {
T& operator[](int) const; II indexed array access (binary)
T& operator*() const; II pointer dereference (unary)
};

II if type is pointer-to-const-like (i .e .. PC = const T*)

class PC {
const T& operator[](int)const; II indexed array access (binary)
const T& operator*()const; II pOinter dereference (binary)
};

Figure 9-4: Summary of Properties of Some Fundamental Operators

Section 9.1.2 Free or Member Operator 591

Notice that unary operators that do not modify their arguments are not fundamentally
members. For example, unary operator! works perfectly on a user-defined type such
as an ostream even though there is no ! operator defined for this type:

#include "iostream.h"
void g(ostream& out)
{
if (!out) {
cerr « "output stream is bad" « endl;
return;
}
// ...
}

The code above works because an ostream knows how to convert itself implicitly to a
fundamental type (va; d *) for which the! operator is defined. If operator! were
treated as a member of a hypothetical v 0 i d* class definition, no user-defined conver-
sion could occur and the above code would result in a compile-time error.

If we want to disable implicit conversion of the argument to the "free" unary

operator!, we can remain consistent with these guidelines simply by making the!
operation a member function-e.g., obj . not ( ) instead of an operator. 10

9.1.2 Free or Member Operator

The decision of whether to make an operator function a member or a free function is

entirely defined by whether implicit type conversion of the leftmost operand is desir-
able. If the operator modifies this operand, such conversion is definitely not desirable.

The C++ language itself serves as an objective and relevant standard

after which to model user-defined operators.

Consider what could happen if we defined the concatenation operator (+=) for a string
class to be a free function instead of emulating the approach taken for the fundamental

10 See also murray, Section 2.5, -po 44.

592 Designing a Function Chapter 9

types. As Figure 9-5 illustrates, making 0 per at 0 r+= a free function has enabled the
implicit conversion of its left-hand con s t c ha r * operand to a temporary p ub_St ring
(denoted here as tOO 5) with f 0 0 as its value. Even though this temporary would be an
rvalue for fundamental types, it is the temporary p ub_S t r i n9 object that then has the
value ba r" concatenated to it (and is not a compile-time error).11 As this behavior
II

would likely surprise and annoy our clients, we would be wise to suppress it.

II pub_String.h
// ...
class pub_String {
I I ...
public:
pub_String(const char *str);
};

pub_String& operator+=(pub~String& left, const pub_String& right);

II free-function definition of concatenation for strings

I I ... #include "pub_string.h"

void f()
{
pub_String a("tar");
const char *b = "foo";
pub_String c("bar");
b += c; II has no effect

b += c

(pub_String) taOS
(" bar" concatenated
(pub_String) t005 . - to temporary copy
of pub_St ri ng)
a += b += c; II a now holds "tarfoobar"
II but b remains unaffected.
}

Figure 9-5: Result of Implementing operator+= as a Free Function

11The C++ Language currently permits the modification of unnamed temporaries of user-defined
type. See murray, Section 2.7.3, pp. 53-55.
Section 9.1.2 Free or Member Operator 593

On the other hand, we expect certain operations (e.g., + and ==) to work regardless of
the order of their arguments. Consider 0 per a t 0 r+, which is used to concatenate two
strings and return its result by value. The language allows us to define 0 per at 0 r+ as
either a member or a non-member. The same goes for operator==. If we elect to
define these operators as members, then we will subject our clients to the following
anomalous behavior:

void f()
{
pub_String s("foo"), te"");
i nt i;

t - s + "bar"; II ok
t - "bar" + s ; II error
1 - S -- "bar"; II ok
1 - "bar" - - s ; II error
}

The problem is that

pub_String::operator+(const String& right)

and

pub_String::operatar==(const String& right)

enable a char * to be implicitly converted to a pub_String on the right via a con-

structor of the fonn

pub_String::pub_String(const char *)

while no such conversion on the 'left is possible.1 2 Making these operators free solves
the symmetry problem until we add the conversion operator

pub_String: :operatar canst char *() canst

to the pu b_S t r i n 9 class.

Figure 9-6 illustrates a problem brought about merely by adding a conversion (cast)
operator from a pub_St ring to a can s t ch a r *. Strangely, the two apparently similar
operators == and + are not identical with respect to overloading as (naively) we would

12 ellis, Section 13.4.2, p. 333.

594 Designing a Function Chapter 9

like to believe. The difference lies in the fact that there are now two ways to interpret
the == operator:

1. Implicitly convert the c ha r * to a p ub_S t r i n9 and compare using

operator==(const String&, canst String&).

2. Implicitly convert the pub_St ring to a can s t ch a r * and compare using

the built-in == for pointer types.

The problem does not exist for the + operator because there is no way to "add" two
pointer types in C++; hence there is no ambiguity.

II pub_String.h
I I ".
class pub_String {
I I ...
public:
pub_StringCconst char *pcc):
I I ...
operator const char *() const; II (== new conversion operator
};

int operator==(const String& left. canst String& right);

String operator+Cconst String& left. const String& right);

I I ... #include "pub_String.h"

void f()
{
pub_String s("foo"), te"");
i nt i;

t - s + "bar"; II ok
t - "bar" + s ; II ok
1 - s -- "bar"; II error (ambiguous)
1 - "bar" -- s ; II error (ambiguous)
1 - strlen(s); II ok
}

Figure 9-6: Ambiguity Resulting from both Conversion Operators

In a real-world string class, we would never rely on the implicit conversion to obtain
the string value for fear that the extra construction and destruction would unduly
affect our performance. Instead, we would define separate overloaded versions of
Section 9.1.2 Free or Member Operator 595

ope rat 0 r+ to handle each of the three possibilities as efficiently as possible, thus
sidestepping these ambiguity problems.

Inconsistencies in overloaded operators can be obvious, annoying,

and costly to clients.

As Figure 9-7 illustrates, in order to accept a con s t c ha r * on the left of the == operator,
we are forced to make at least one of the equality operators functions a free function.

class pub_String {
I I ...
public:
pub_String(const char *pcc);
operator canst char *() canst;
int operator==(const char *pcc) canst; II bad idea: (asymmetric)
II Allows for user-defined' conversion only for the
II argument on the right side of the operator.
};

int operator==(const pub_String& left, const pub_String& right);

int operatar==(const char *left, const p~b_String& right);
II Allows for user-defined conversion on both the
II left and right arguments symmetrically.

struct Foo {
F00 ( ) ;
operator const pub_String& () canst;
II Implicitly convert a Foo to a pub_String,
};

struct Bar {
Bar();
operator canst char *() canst;
II Implicitly convert a Bar to a (canst char *).
};
596 Designing a Function Chapter 9

void g()
{
Faa faa;
Bar bar;
if (bar == faa) { II ok: Bar =to=) (canst char *)
I I ... Faa =ta=) (canst pub_String&)
}
if (faa == bar) { II error: Faa =NO=) (const pub_String&)
I I ... Bar =to=) (canst char *)

Figure 9-7: Result of Implementing 0 per at 0 r= as a Member Function

As long as we are supplying all three versions of the operatar== function, what harm
could it do to make one a member? The hann is that a lack of symmetry could sur-
prise our clients. In the event that one object can be implicitly converted to
pub_S t r i n9 and the other to a can s t c ha r *, we would still expect the order of com-
parison to be unimportant. That is, if bar == f a a compiles, then so should fa 0 == bar
(and produce the identical result at runtime). However, if the

int aperator==(const pub_String&, canst char *);

version is not available as a free function, then there is no way for the following
implicit conversions to occur:

f 0 bar

implicit conversion implicit conversion

of Foa to of Sa r to
canst pub_string& canst char *

(pub_String) t006 (canst char *) t007

(pub_String) t008

The conclusion is that 0 per at 0 r== should always be a free function, regardless of
what other functions are involved. The same reasoning holds for the other binary
operators that do not modify either operand and return their result by :value.
Section 9.1.3 Virtual or Non-Virtual Function 597

The example set forth by the language itself is an impartial and useful model that cli-
ents can exploit to infer basic syntactic and axiomatic properties of operators.- The
goal of modeling the fundamental operations is not to enable implicit conversions
unnecessarily, but rather symmetrically to avoid surprises. If operator overloading is
used to any great extent, it is reasonable to expect that the abstraction is suitable for
reuse in a variety of situations. Clients of reusable components will appreciate a con-
sistent and professional interface-devoid of syntactic surprises. Note that the C++
language requires that the following operators be members: 13

Assignment
[] Subscript
-) Class member access
() Function call
(T) Conversion ("cast") operator
new (static) allocation operator
del e t e (static) deallocation operator

9.1.3 Virtual or Non-Virtual Function

Dynamic binding enables member functions accessed through a base class to be

determined by the actual subtype of the object, as opposed to the type of the pointer or
reference used in the call. A function must be declared vir t ua 1 in order to be dynam-
ically bound. Only member functions can be virtual in C++. However, the conclusion
that polymorphic behavior of an operator requires it to now become a member where
it would otherwise have been a free function is erroneous.

Syntactic issues, such as symmetric implicit conversion for binary

operators, need not be compromised in order to achieve polymorphic
behavior.

13 ellis, Section 12.3c, p. 306; stroostrup94, Section 3.6.2, pp. 82-83.

598 Designing a Function Chapter 9

II geom_shape.h
#ifndef INCLUDED - GEOM - SHAPE
#define INCLUDED_GEOM_SHAPE

class geom_Shape {
public:
virtual ~geom_ShapeC);
virtual canst void *classld() const = 0;
virtual int compare(const geom_Shape& shape) const = 0;
II Returns negative. zero. or positive corresponding to
II whether this geom_Shape object is less than. equal to, or
II greater than the specified geom_Shape object. respectively.
};

inline int operator==(class geom_Shape& left. class geom_Shape& right) {

return left.compare(right) == 0; }

inline int operator!=(class geom_Shape& left, class geom_Shape& right) {

return left.compare(right) != 0; }

inline int"operator<=(class geom_Shape& left, class geom_Shape& right) {

return left.compare(right) <= 0; }

inline int operator<Cclass geom_Shape& left, class geom_Shape& right) {

return left.compare(right) < 0; }

inline int operator)=Cclass geom_Shape& left. class geom_Shape& right) {

return left.compareCright) )= 0; }

inline int operator)Cclass geom_Shape& left. class geom_Shape& right) {

return left.compareCright) 0; }

#endif

Figure 9-8: Polymorphic Comparison of Shapes Using Free Operators

Section 9.1.3 Virtual or Non-Virtual Function 599

Figure 9-8 illustrates how symmetric operators can and should continue to remain free
even in the presence of polymorphic behavior. Instead of making each of the six
equality and relational operators virtual members of the class, a single virtual com-
pare member is provided. These six operators will now continue to behave symmetri-
cally with respect to any implicit conversion.

Equality operators often make sense even when the relational operators do not (think
of a point abstraction). Sometimes sorting a heterogeneous collection allows for more
efficient access. In such cases, any ordering (even an arbitrary one) can be useful. The
virtual c 1 ass I d () method in Figure 9-8 enables derived types to define their own
runtime type identifier. 14 Using this identifier, shapes of the same type can be sorted
according to their own internal ordering, while ordering across concrete types can be
defined by some different (perhaps arbitrary) comparison. An implementation of a
geom_Ci rcl e, which participates in a total order on shapes, is provided succinctly for
reference in Figure 9-9.
600 Designing a Function Chapter 9

II geom_circle.h
#ifndef INCLUDED_GEOM_CIRCLE
#define INCLUDED_GEOM_CIRCLE

#ifndef INCLUDED_GEOM_SHAPE
#include "geom_shape.h"
#endif

class geom_Circle : public geom_Shape {

static canst void *d_classld_p;
double d_radius;

public:
geom_Circle(double radius) : d_radius(radius) {}
geom_Circle(const geom_Circle& circle) : d_radiusCcircle.d_radius) {}
-geom_Circle(const geom_Circle& circle);
geom_Circle& operator=(const geom_Circle& circle) {
d_radius = circle.d_radius; return *this; }
canst void *classld() const { return d_classld_p; }
int compare(const geom_Shape& shape) const; II virtual
int compare(const geom_Circle& circle) const; II non-virtual
};

inline int operator«class geom_Circle& left, class geom_Circle& right) {

return left.compareCright) < 0; }

II Cdefinitions of other 5 symmetric operators omitted)

#endif II geom_circle.c
#include "geom_circle.h"
canst void *geom_Circle: :d_classld_p = &d_classld_p; II runtime type id
9e 0 m_ Ci r c 1e: : ---9e 0 m_ Ci r c 1e () {}. I I em pt Y & 0 ut - 0 f - 1i ne (s e e Sec t ion 9. 3 . 3 )

int geom_Circle::compareCconst geom_Shape& shape) const

{
return shape.classldC) == d_classld_p ?
compare«const geom_Circle&) shape) II compare instances
d_classld_p < shape.classldC) ? -1 : 1; II compare types
}

int geom_Circle::compareCcanst geom_Circle& circle) const

{
return d_radius < circle.d_radius ? -1 : d_radius > circle.d_radius;
}

Figure 9-9: Implementation of Polymorphic Comparison for geom_Ci rcl e

Section 9.1.3 Virtual or Non-Virtual Function 601

Virtual functions implement variation in behavior; data members

implement variation in value.

More generally, virtual functions are used to describe variation in behavior across
types derived from a common base class. Data members, however, are sufficient for
describing variation in value without having to resort to inheritance. 15 For example,
we would not define a protocol class art_Color, and then derive classes art_Red,
a rt_B 1 ue, and a rt_ Ye 11 ow; a single (perhaps fully insulating) concrete art_Co lor
class that stores one of a number of enumerated colors is probably a more appropriate
design. However, virtual functions are an effective technique for breaking both com-
pile-time and link-time dependencies (see Section 6.4.1). For that reason, a single
concrete class might be derived from an art_Co lor protocol.

DEFINITION:
Hide: A member function hides a function with the same
name ·declared in a base class or at file scope.
Overload: A function overloads the name of another function
with the same name defined in the same scope.
Override: A member function overrides an identical function
declared virtual in a base class.
Redefine: The default definition of a function is irretrievably
replaced by another definition.

15 See cargill, Chapter 1, pp. 16-19.

602 Designing a Function Chapter 9

Finally, there are four similar terms that are commonly used (and misused) to describe
a function and its effect on other functions (hide, overload, override, and redefine)
that we define here for reference. Distinct functions with the same name are said to be
overloaded only if they are declared in the same scope. When a member function in a
derived class is declared with the identical interface of a function declared virtual in a
base class, that function is said to override the base class function. In all other cases, a
function name hides all identically named functions in an enclosing scope, regardless
of their argument signatures. Functions hidden in a named scope are not directly
accessible, but can be accessed via the scope resolution operator (: :). However, when
we redefine a function (e.g., global new or class specific unary &), we replace its defi-
nition; the previous definition is no longer accessible from the program. I6

Guideline

Avoid hiding a base-class function in a derived class.

We should be careful not to hide the definitions of any base-class functions in derived
classes. In particular, we should never supply a new definition for a non-virtual func-
tion in a derived class, since that would make the function sensitive to the type of any
pointer or reference from which the function might be called. I7 Allowing the type of
the pointer or reference to affect which behavior is invoked is counterintuitive, subtle,
and error prone. Hiding functions defined in base classes does not protect them from
use; it merely makes such use more cumbersome. We can always fiddle with the
pointer or use the scope resolution operator to call the hidden member. A better idea is
simply never to hide a member function in the first place. An example of a design pat-
tern involving virtual functions, multiple inheritance, and runtime type identification
can be found in Appendix C.

16 ellis,
Section 10.2, p. 210, and Section 13.1, p. 310.
17 See meyers, Item 37, pp. 130--132. .
Section 9.1.4 Pure or Non-Pure Virtual Member Function 603

9.1.4 Pure or Non-Pure Virtual Member Function

Declaring a virtual function to be pure forces the concrete derived-class author to sup-
ply a definition. If failing to supply a specific behavior in a derived class is likely to be
an error, then the virtual function should be declared pure in the base class.

Protocol classes (see Section 6.4.1) are useful for achieving both levelization and
insulation in inheritance hierarchies. We want to avoid defining any behavior in the
protocol class itself; making all of the member functions (except the destructor) pure
virtual enables us to avoid defining any of them.

An abstract class derived from a pure protocol is sometimes referred to as partial

implementations. Protocol functions that are not declared in the derived class are
inherited as pure virtual. Some functions in a partial implementation may have a use-
ful default behavior, but they should not necessarily default automatically. As illus-
trated in Figure 9-10, both defining a virtual function and declaring it pure forces a
derived-class author to enable the default behavior explicitly.I8

#include <iostream.h>

struct Base { II *** Base Class ***

virtual void f() - 0;
virtual -Base();
};

Bas e : : '"""B as e () {}

struct Partial: Base { II *** Partial Implementation ***

virtual void f() = 0; II declaration of pure virtual function
-Partial();
};

void Partial::f() II definition of pure virtual function

{
cout « "Parti al: :f" « endl:
}

Partial::'"""Partial() {}

18 See ellis, Section 10.3, p. 214.

604 Designing a Function Chapter 9

'struct Derived: Partial { II *** Concrete Derived Class ***

Derived() {}
void f();
~Derived();
};

void Derived::f()
{
cout « "Derived: :f" « endl;
Partial::f(); II explicit call of pure virtual function
}

Derived::'"'"'Derived() {}

maine)
{ II *** Main Program ***
Base *b - new Derived;
b-)f();
}

II Output:
II john@john: a.out
II Derived::f
II Part i a 1 : : f
II john@john:

Figure 9-10: Forcing Default Behavior to Be Enabled Explicitly

9.1.5 Static or Non-Static Member Function

The obvious reason for making a function a static member of a class is that it does not
depend on any particular instance of an object:

class my_Widget {
static int d_instanceCount;
I I ...
public:
static int instanceCount() { return d_instanceCount; }
I I ...
};

.
Static member functiQns are commonly used to implement non-
primitive functionality in a separate utility class.
Section 9.1.6 canst Member or Non-canst Member Function 605

Escalating functionality to a higher level may require making it a static member func-
tion of a type defined in some other component (see Figure 5-15). If the function is a
convenience function that does not require private access, we might consider making
the function a static member of a separate class to emphasize its non-primitive status.

class geom_Point { 1* ... *1 };

struct geom_PointUtil {
static int compareMagnitude(const Point& a, const Point& b);
II Compare the distance of each point from the origin,
II and return a negative, zero, or positive value
II depending on whether the magnitude of a is less than,
II equal to, or greater than that of b, respectively.
};

Notice that by making the campa reMagn.i tude a static function, we retain symmetry
with respect to the implicit conversion of its arguments. Had we instead declared
campareMagnitude a non-static member of geom_Point, there could be cases where
a . compa reMagni tude (b) would compile but b. campa reMa gni tude (a) would not
(see Section 9.1.2).

Though rarely necessary, we could grant private access while retaining this symmetry
just by moving the static method inside the geam_Poi nt class itself.

9.1.6 canst Member or Non-canst Member Function

A member function should be declared can s t in order to remove unnecessary restric-

tions on its use wherever this is appropriate. 19 There are two notions of canst-ness:
logical and physical. Logical can s t-ness is more nebulous and refers to what the user
is meant to perceive as can s t; changes to the internal organization that are program-
matically undetectable by the client are considered logically canst. On the other
hand, the C++ language enforces physical canst-ness. A member function can be
declared con s t so long as it (1) does not modify the bits contained directly in the
structure that defines the class, or (2) does not return a non-con s t pointer or reference
to any data member embedded in that structure.

Figure 9-11 illustrates how physical con s t-ness is enforced in C++. A con s t member
function is permitted to modify and return a writable reference to memory that is held

19 See meyers, Item 21, pp. 73-78.

606 Designing a Function Chapter 9

and managed by an object. Since all of the functions defined above cause or enable
side effects that are programmatically accessible by clients, none would be considered
logically con s t functions.

class ex_String {
char *d_str_p;

public:
I I ...
makeNull() { d_str_p = O;} II physically nan-canst
rna ke Empty ( ) canst { d_str_p[OJ = 0; } II physically canst

char *&getRepRef() {return d_str_p;} II physically nan-canst

char * getRepC) canst { return d_str_p;} II phYSically canst
};

Figure 9-11: The C++ Language Enforces Physical canst-ness Only

DEFINITION: An object is canst-correct if a function taking only a

single argument that is a canst reference to that object is not able,
without explicit casting, to obtain a non-canst reference to that same
object (or a portion thereof) from within the function body.

Guideline

Every object in a system should be canst-correct.

Deciding what is and what is not canst behavior of an object is an important part of
the design of its class (see Section 10.3.1). Care must taken to ensure that there are no
loopholes that could allow a client to circumvent that decision. Returning writable
access to an object's internal representation from a con s t member function can short-
2o
circuit the ability of the compiler to help ensure that a can s t object is not modified.

20 meyers, Item 29, pp. 96-99.

Section 9.1.6 canst Member or Non-canst Member Function 607

Returning a non-canst object from a canst member function can rup-

ture the canst-correctness of a system.

class te_Node { class te_Node {

I I ... I I ...
public: public:
II II

II MANIPULATORS II MANIPULATORS
void setValue(double v); void setValue(double v);
te_Node *parent();
te_Node *childl();
te_Node *child2();

II ACCESSORS II ACCESSORS
canst char *name() const; canst char *name() const;
te_Node *parentC) const; const te_Node *parentC) const;
te Node *childlC) const; canst te_Node *childlC) canst;
te_Node *child2() const; const te Node *child2() const;
}; };

a) Not canst Correct b) canst Correct

Figure 9-12: Dlustrating canst-Correctness

When designing the system, it is easy to inadvertently provide ways in which a non-
con s t version of a reference to an object can be obtained from a con s t reference to
that same object. For example, Figure 9-12 provides two definitions of a t e_N 0 d e
used to implement a binary tree. Figure 9-12a defines canst member functions that
return writable access to the parent and each child. A function taking a reference to a
canst te_Nade could easily modify this supposedly canst value, without ever resort-
ing to a cast, as follows:

void f(const te_Node& readonlyNode)

{
if (readonlyNode-)childl()) (
te_node *writableNode = readonlyNode-)childi()-)parent();
writableNode-)setValue(-9.99E99):
}
}
608 Designing a Function Chapter 9

In the context of a system, an object that does not allow a non-canst reference to an
object to be obtained from a canst reference to that same object alone (either directly
or indirectly) is said to be canst-correct. Figure 9-12b defines a class that does not
provide a way to obtain writable access from a can s t reference through indirect
means. This implementation is can s t-correct because it preserves the intent of what
can and cannot be done with a canst te_Nade alone.

DEFINITION: A system is canst-correct if there is no way (without

using an explicit cast) for a function taking only canst reference
arguments to any subset of objects within the system to obtain a writ-
able reference to any of these objects (or any portions thereof) from
. within the body of the function.

In other words, given an arbitrary function:

void fCconst Tl& aI, canst T2& a2, 000, canst TN& aN)
{
II There is simply no way for me to get hold of a
II writable reference to any of aI, a2, ... , aN or
II any portion thereof (short of casting away canst).
}

Guideline
A system should be canst-correct.

canst-correctness is a property that extends beyond a single class or component and

applies to an entire system. For example, class Nade in Figure 5-8 is suspect because it
contains a function

Edge& Node::edgeCint index) canst;

that allows a client to obtain a modifiable Ed 9 e from a can s t Na de. Even if Ed 9 e were
to have been careful to perpetuate the canst-ness as shown here:

Nade& Edge::to(); Node& Edge::fram();

canst Nade& Edge::ta() canst; canst Nade& Edge::fram() canst;
Section 9.1.6 con s t Member or Non- con s t Member Function 609

as long as we can obtain a non-canst reference to a Nade from a non-canst Edge, the
subsystem is not canst-correct:

void f(const Node& readonlyNode)

{
if (readonlyNode-)numEdges() ) 0) {
Edge& writableEdge = readonlyNode-)edgeCO);
Node& writableNode = (&writableEdge-)to() == this) ?
writableEdge-)to() :
writableEdge-)from();

II writableNode is a writable reference to readonlyNode!

}
}

In a heterogeneous network of objects, a canst member of one type can be exploited

to undermine the canst-correctness of another. The problem can be illustrated graph-
ically, as shown in Figure 9-13a. In this conversion graph, every type in the system
has both a non-canst and a canst representation. Converting from the non-canst
(down) to the can s t version of a type is automatic. Member functions of a type X that
return a pointer or reference to a type Y are represented in the conversion graph with
the appropriate directed edge from the appropriate version (i.e., canst or non-canst)
of type X to the appropriate version of type Y.

non-const:

(a) Contains canstINon-canst Cycle (b) Is can s t-Correct

Figure 9-13: Establishing canst-Correctness Graphically (see Figure 9-12)

Since Ed g e defines a can s t member that returns a reference to a can s t Na de, there is
a directed edge from canst Edge& to canst Node&. The non-canst version of this
method is treated analogously. The problem is that Nade contains a canst member
that returns a non-canst Edge reference-hence the upward sloping diagonal entry in
610 Designing a Function Chapter 9

Figure 9-13a. This diagonal entry introduces a cycle that contains both the canst and
the non-canst versions of Nade. Consequently, given a canst reference to a Node, we
can potentially obtain a non-canst reference to the identical Nade. A similar cycle
involves both versions of Edge, so a canst Edge reference 'could be converted to nOD-
can s t without the use of a cast.

DEFINITION: A system is canst-correct if its conversion graph con-

tains no cycle that involves both the canst and non-canst versions of
anyone type.

The conversion graph shown in Figure 9-13b reflects the definition of Nade given in
Figure 9-12b. There are conversion cycles between Node& and Edge&, and also
between canst Nade& and canst Edge&. However, there is no one cycle that involves
both versions of either type; this small subsystem is can s t-correct. This interpretation
of canst-correctness generalizes to apply to an entire system.

It is possible that an object may supply canst information, such as a name that could
then be used to look up a writable version of the same object in some non-canst con-
tainer object:

void gCte_Tree *t, te_Node& readonlyNode)

{
te_Node *writableNode = t->lookupCreadonlyNode.nameC));
writableNode->setValueC-9.99E99);
}

The above is not a violation of canst-correctness because the canst object alone is
not enough to obtain a non-canst version of itself. Had the te_Tree been passed by
canst reference, we would expect that a canst version of the te_Tree: :lookup
member function would instead return a pointer to a canst te_Nade,ensuring the
canst-correct system shown in Figure 9-14.
Section 9.1.6 canst Member or Non-const Member Function 611

non-const:

Figure 9-14: A canst-Correct Implementation of te_Tree and te_Node

There are situations where we do want a const member to return a non-canst refer-
ence or pointer to another type. In the Poi ntIt e r Han d 1e of Figure 6-75, we are able
to access a writable version of the contained Poi ntlter from a reference to a const
handle:

Pointlter *PaintlterHandle::operator-)C) canst;

The intent here was to emulate the semantics of a writable pointer passed by value-
that is, you can modify the indicated object but you cannot change the handle itself to
refer to a different object. 21 However, as Figure 9-15 illustrates, this subsystem is
con s t-correct because there is no way to obtain a writable Poi ntIt e r Han d 1e refer-
ence from either kind of Po i nt I te r.22

21 The usefulness of a canst iterator obtained from a handle passed to a function by const reference
is dubious.
22 Note that verifying canst-correctness for a system can be done through static analysis; however,
because violating canst-correctness can depend on the underlying object (instance) network, it is
possible to have a canst-correct system that cannot statically be proven to be so. Such systems are
more expensive to maintain and much harder to validate.
612 Designing a Function Chapter 9

non-canst:

Figure 9-15: A const-Correct Implementation of Poi ntIterHandl e and Poi ntIter

Ignoring canst-correctness implies that an argument passed to a function by canst

reference may "legitimately" be modified within that function. Respecting canst-
correctness improves the consistency of the system and enables the compiler to detect
a wider class of errors at compile time than would otherwise be possible.

Guideline
Think twice (at least) before casting away const.

Casting away canst-ness serves to undermine all the benefits we worked so hard in
this section to achieve.

9.1.7 Public, Protected, or Private Member Function

Member functions intended for direct use by general clients must be declared pub 1; c.
Free operators such as the equality or relational operators may be implemented in
terms of a primitive member function (see Figure 9-21). If this primitIve member
function is not public, the dependent free operators will need to be declared friends of
the class, which lessens maintainability and enables abuse (see Section 3.6).
Section 9.1.7 Public, Protected, or Private Member Function 613

Member functions that are not public expose general users to uninsu-
lated implementation details.

Private member functions are intended for use within a class and by friends of a class.
Since friendship outside a component is discouraged, there is often little advantage to
non-virtual private member functions over static free functions defined at file scope in
the. c file (see Section 6.3.3). One common valid use of a private non-virtual member
function is to factor out complex but seldom needed behavior from an otherwise tiny
and frequently called inline function. For example, class my_Stack in Figure 10-13
uses the private non-inline member 9 rowAr ray ( ) to implement the public inline pus h
method:

i n1i ne
void my_Stack::push(int value)
{
if (d_sp )= d_size) {
growArray() ;
}

Without using private methods, we would be forced either to implement the entire
push method out-of-line with a significant cost in performance, or to violate encapsu-
lation by making the growArray method public. Trying to implement the entire push
function inline is probably out of the question.

Private virtual functions make sense when the behavior defined in a derived class is
used only by members and friends of the base class. A potential use of a private vir-
tual function can be found in the sur f ace Equa t ion member of class Sol i d described
in Section 6.6.3 (see Figure 6-84).
614 Designing a Function Chapter 9

All virtual and protected functions are intended for consideration by

derived-class authors.

Protected member functions are explicitly earmarked for derived-class authors. Pro-
tected member functions expose general clients to implementation details and are
often best avoided (see Section 6.3.4). Although private virtual function are not acces-
sible to derived classes, derived-class authors may be expected to supply definitions
for these functions; in this sense, private virtual functions are exceptional:

c 1 ass Ba s e {
private:
virtual void programMe();
};

class Derived: public Base {

public:
void programMe(); II The derived class itself cannot call this
II function through the base-class interface;
II yet even clients of the derived class's public
II interface are able to access this function.
};

9.1.8 Return by Value, Reference, or Pointer

The issue of whether to return by value or not comes down to whether there is some-
thing within the object or argument list suitable to reference. For example, there is no
reasonable implementation23 of

pub_String& operator+(const pub_String& left, canst pub_String& right);

As we saw in Section 8.3, returning an object by value preserves total encapsulation

but can be significantly more expensive at runtime than returning a pointer or refer-
ence. For non-operator functions, we have the additional option of r~turning an object
through the argument list. Return by argument is usually more efficient than return by

23 See meyers, Item 23, pp. 82-84; Item 31, pp. 102-105.
Section 9.1.8 Return by Value, Reference, or Pointer 615

value, and yet it is still fully encapsulating. The four ways to return a (F 00) value are
summarized in Figure 9-16.

Foo v( ... ); II return by value

canst Foo& r( ... ); II return by reference
const Foo *p( .. ~); II return by pointer
int a(Foo *retVal, .. . ) ; II return by argument

int a(Foo& retVal, . . . ) ; II bad idea (see Section 9.1.11)

Figure 9-16: Four Ways to Return a Value from a Function

In cases where the function may fail, return by value or reference may not an option. 24
Sometimes we can return the value by pointer, which can be 0 on failure. Another
option is to return an integer status to indicate success or failure, and to return the
object itself through the argument list.

Guideline
For functions that return an error status, an integral value of 0 should
always mean success.

For functions that return an error status as either an i nt or some enumerated type, it is
convenient to have a way of knowing whether or not this function worked25 without
having to inspect some header file to determine the appropriate success value for this
particular function. Traditionally, a status of zero indicates success, a non-zero status
indicates failure, and the particular non-zero value may be used to provide additional
information to clients.

24 Sometimes it may make sense to return an object in a class-defined "invalid" state.

25 Note that a function such as f e los e performs an operation and returns an error status regarding
the outcome of that operation. A function such as i sa 1pha merely answers a yes-or-no question with
no preconceived notions of success or failure. Consequently, fel ose returns an error status, while
i sa 1pha does not.
616 Designing a Function Chapter 9

Often there is exactly one way for a function to work and several
ways for it to fail; as clients, we may not care why it failed.

Very often, clients will not care why an operation failed; in such cases a simple test
for non-zero status is sufficient, as indicated in Figure 9-17. In some cases, this con-
vention may allow us to avoid including an additional header enumerating the error
conditions, thereby reducing unwanted compile-time coupling.

Although redundant, this a initializer

indicates that the value of the
enumerator is not arbitrary.
int f( ... )
{
enum { GOOD = 0, BAD, UGLY} status = GOOD:

if (01= g( ... )) {
status = BAD;
I I ...
}

if (GOOD ==status && 0 1= h( ... ») {

status = UGLY;
I I ...
}

II

return status;
}

Figure 9-17: 0 == Success for All Functions that Return Status

For non-canst member functions, returning a non-canst reference to the object itself
is always a viable option. Returning a pointer or reference to an internal part of the
object potentially limits the implementation choice; its impact on encapsulation
should be considered carefully (see Section 8.3).
Section 9.1.8 Return by Value, Reference, or Pointer 617

Returning a dynamically allocated object by loading a modifiable

handle argument is less prone to memory leaks than returning that
object by non-canst pointer.

For polymorphic objects such as geom_Shape (see Figure 9-8), it is not possible to
return an object by value. Returning a clone (dynamic copy) of the object by non-
eon st· pointer places the burden of deallocation on the client, and is prone to memory
leaks. The use of a reference here would be obscure and inappropriate (see Section
9.1.11). A preferred approach for returning newly allocated polymorphic objects
would be to pass in a pointer to a handle (see Section 6.5.3) explicitly designed to
hold a pointer to the base class geom_Shape:

class geom_ShapeUtil {
void create(geom_ShapeHandle *handle, canst char *typeName);
II Create a new shape of the type specified by typeName and
II load it into the handle passed in via a non-canst pointer.
};

Guideline
Functions that answer a yes-or-no question should be worded appro-
priately (e.g., i sVal i d) and return an i nt value of either 0 ("no") or 1
("yes").

Finally, it is helpful for functions that explicitly answer a yes-or-no question to be

worded to indicate this fact-i s Aeu te ( ), has Protoco 1 ( i d ), are Par all e 1 ( 1 i ne 1 ,
1 i ne 2 ), and so forth. -and to return an i n t value of a for "no" and 1 (nothing else)
for "yes." By emulating the behavior of built-in operators such as == that return Boolean
values, we help to make the semantics of these common functions clear. Sometimes
clients will depend on the 1 value where they need not:

if (1 == angle.isAcute(» { 1* ... */ }
618 Designing a Function Chapter 9

If .you cache this value as a flag in the object, you might be tempted to retum a
masked bit that could have some non-Boolean value (e.g., 8). Converting a non-Bool-
ean value x to a Boolean value y is as simple as y = !! x. An appropriate implementa-
tion of i sAcute might look as follows:

int geom_Angle::;sAcute() canst

{
return lied_flags & ACUTE_MASK);
}

Since the ANSIIISO committee has adopted boal as a distinct integral type in C++,
we should probably consider returning baal instead of i nt in such cases once this
new fundamental type becomes generally available: 26

bool geom_Angle::;sAcute()canst.
{
return d_flags & ACUTE_MASK:
}

At least now the conversion to a Boolean value is implicit and automatic.

9.1.9 Return const or Non-const

In an effort to eliminate unnecessary restrictions, we strive to take canst operands

and return non- can s t results while maintaining can s t-correctness. 27

Guideline
Avoid declaring results returned by value from functions as canst.

Results returned from a function by value are rvalues. In the case of fundamental
types, declaring an rvalue can s t is redundant, confusing, and can interfere with tem-
plate instantiation:

const int f(); II redundant use of const

26stroustrup94, Section 11.7.2, pp. 254-255.

27 meyers, Item 21, pp. 73-78.
Section 9.1.10 Argument Optional or Required 619

An rvalue of a user-defined type (e.g., an object returned by value from a function)

can be manipulated by non-canst member functions; an object returned by value as
can s t cannot. This latter behavior is a "comer" of the language that is both conten-
tious and may not be implemented consistently across current compilers and plat-
forms. Since the value returned is a copy anyway, exploiting the notion of a can s t
versus a non-con s t rvalue is typically unnecessary.

In general, returning a value by can s t pointer or reference is less restrictive on the

implementation than returning a non-canst pointer or reference. In the sparse array
implementation of Poi ntArray (discussed in Section 8.3), for example, it is conve-
nient to return a can s t reference to a dummy empty object. If the reference were non-
canst, we would be forced to allocate a new object at that location. Note that canst
member functions are obliged not to return non-canst objects that would violate
can s t-correctness (see Section 9.1.6).

9.1.10 Argument Optional or Required

Having just one function body is often easier to maintain than several overloaded ver-
sions. 28 In most cases it is easy enough to use inline functions to create overloaded
versions that, in effect, allow optional arguments to be located in the middle of an
argument list. 29

. Ift~~b~ .
····.· •··•·•

I·
. .•..•.•·•...•··•··.•·· ........... ,., . . , ........... ,.,.................. ... .. •. . .•. . . . . . . .•. •. •. . . •. . •.•. .•. .•·•·•.· •.······.···.··.··.····.1

Default arguments can be an effective alternative to function over-

loading, especially where insulation is not relevant.

Figure 9-18 contrasts the use of overloaded functions with that of default arguments
for factoring common code within a constructor call. As shown in Figure 9-18a, fac-
toring the implementations of several overloaded constructors requires the use of an
auxiliary function i nit, since one constructor cannot usefully be called from
another. 3o Such factoring does not allow us to take advantage of the initialization lists

28 See cargill, Chapter 2, p. 32; Chapter 3, p. 65; and Chapter 4, p. 87.

29 ellis, Section 8.2.6, p. 142.
30 meyers, Item 24, pp. 85-87.
620 Designing a Function Chapter 9

of the constructors. The use of inline functions in Figure 9-18a to forward calls from
several overloaded functions (sometimes referred to as inline forwarding) eliminates
the potential overhead of nested function calls. At the same time, inline forwarding
negates the insulating value of having separate overloaded functions implemented
out-of-line.

geom_Point { geom_Point
int d_x; int d_x;
int d-y; i n t d-y:

private:
void init (x, y);

public: public:
geom_Point (); geom_Point(int x = 0, int y = 0);
geom_Point (int x, int y);
// ... // ...
}; };

geom_Point operator+(const Point&, geom_Point operator+(const Point&,

const Point&); canst Point&);

inline inline
void geom_Point::init(int x, int y) geom_Point::geom_Point(int x, int y)
{ d_x(x)
d- x = X', , d-y(y)
d-y = y; {
} }

inline
geom_Point::geom_Point()
{
init(O,O);
}

inline
geom_Point: :geom_Point(int x, int y)
{
initex, y);
}

(a) Using Overloaded Functions (b) Using Default Arguments

Figure 9-18: Factoring Common Constructor Code

Figure 9-18b illustrates a great economy of notation compared to factoring construc-

tor function bodies. Note, however, that these two implementations are not identical
with respect to the construction of a geom_Poi nt from an i nt:
Section 9.1.11 Pass Argument by Value, Reference, or Pointer 621

void g()
{
geom_Point a = 5;
a = a + 10;
}

The implementation in Figure 9-18a does not allow a geom_Poi nt to be constructed

from a single argument, and so precludes the non-intuitive initialization and implicit
conversion above. Using two default arguments to implement the default constructor
as in Figure 9-18b subtly introduces an undesirable integer conversion operator that
allows the above code to compile silently (see Section 9.3.1).

Default arguments can be more self-documenting, more compact, and more easily
understood by clients than mUltiple overloaded functions because they place more
information in the header file. As such, default arguments are at odds with the goal of
insulation. For more information about how to reduce compile-time coupling when
using default arguments, see Section 6.3.8.

One important use of default arguments is to allow developers to append additional

parameters to functions conveniently, without breaking any preexisting programs that
use them.

Guideline
Avoid default arguments that require the construction of an
unnamed temporary object.

Passing user-defined types as default arguments is cumbersome at best; not all objects
make sense as defaults. Constructing a temporary object to pass in by default, like
passing an object by value, is expensive and should be avoided.

9.1.11 Pass Argument by Value, Reference, or Pointer

Passing user-defined types by value is unnecessary and expensive. This practice is so

costly that it has contributed to the perception that the C++ language itself is SIOW. 31

31 For more justification, see meyers, Item 22, pp. 78-82.

622 Designing a Function Chapter 9

Never pass a user-defined type (i.e., cl ass, struct, or un; on) to a func-
tion by value.

Instead of passing a user-defined type by value, pass it by con s t reference. In the

absence of global variables, the semantics are essentially identical in practice, but the
runtime performance is superior. Enumerations and all fundamental types are most
efficiently passed by value.

When it comes to returning a value through the argument list, there are two mind sets:

1. va i d f ( my _0 b j e c t & res u1 t, ... ); / / ret urn by non - con s t re fer e nc e

2. voi d f(my_Object *resul t, ... ); / / return by non-const poi nter

Wherever feasible, we would like to use the language itself to express our intention
instead of relying on a comment. The C++ language definition states that a pointer
may be null but that a reference may not. Returning a value through a modifiable ref-
erence argument makes the semantics clear: the object to receive the value must be
supplied by the client. Any documentation to reiterate this requirement would be
unnecessary and redundant. Consequently there is no need to test for a null refer-
ence-and there is no portable way to do so anyway. Returning an object by non-
canst pointer can therefore be reserved exclusively for results that are truly optional;
that is, the pointer is always tested inside the function, and if a null pointer is supplied,
the result is not loaded into the object.

In the other camp,32 classical theory discourages functions that modify their argu-
ments; such functions are known to be more difficult to maintain. Remember that, his-
torically, most of the cost incurred over the life of a system is in maintenance and
enhancement-not initial development. Allowing functions to modify their arguments
by reference makes it more difficult for software engineers maintaining an unfamiliar

32 stroustrup, Section 2.3.10, p. 62.

Section 9.1.11 Pass Argument by Value, Reference, or Pointer 623

body of code to know whether an argument passed into a function (apparently by

value) could potentially be modified.

The expressive power of writable references applies only if you happen to look at the
appropriate header file. From looking at just the client code in Figure 9-19, it is not at
all clear what caused the value of the my_String variable name initialized with
La u r e1" to come to hold the (incorrect) value" Hardy" .
II

void g(int i ~ int j)

{
my_String name("Laurel");
I I ...
int s = my_Stuff::funcX(name, i);
I I ...
int t = your_Problem::funcY(name, j);
I I ...
int u = their_Thing::funcZ(name, i + j);
I I ...
cout « II name = " « name « endl;
}

II Output:
II name = Hardy

Figure 9-19: Modifying Function Arguments via Writable References

Functions that actually do modify their arguments are relatively scarce. By adopting
the guideline of modifying function arguments only through non-con s t pointers, we
make such functions easy to spot from the client code. ·Figure 9-20 shows that only
one of the three functions that operate on name could legitimately have modified its
value; in this example, we can look in only one place instead of three, simply by virtue
of having followed this guideline.

Guideline
Be consistent about returning values through arguments (e.g., avoid
declaring non-canst reference parameters).
624 Designing a Function Chapter 9

void g(int i, int j)

{
my_String name("Laurel");
I I ...
int s = my_Stuff::funcXename, i);
I I ...
int t = your_Problem::funcye&name. j);
I I ...
int u = their_Thing::funcZename, i + j);
I I ...
cout « "name = " « name « endl;

II Output:
II name = Hardy

Figure 9-20: Modifying Function Arguments Only via Writable Pointer

Figure 9-21 demonstrates that even in the body of a function that takes a non-canst
pointer argument, we need look no further than the definition of this function (rather
than the header files declaring each called function) to infer which called functions
might modify that argument.

v0 i d f ( my _ St r i n9 * name, 1, j)
{
int s = my_Stuff::funcXe*name, i); II should not modify name
I I ...
int t = your_Problem::funcY(name, j); II potentially modifies name
I I ...
int u = their_Thing::funcZ(*name, i + j); II should not modify name
I I ...
}

Figure 9-21: Nesting Functions that Return via Writable Pointer

Historically, passing objects by pointer and passing objects by reference have not
always been equivalent when it came to user-defined conversions. Until the c++ lan-
guage definition changed for release 2.0 of CFRONT,33 a function taking a non-canst
reference to you r _C 1ass would allow its argument to undergo a user-defined conver-
sion to a temporary before the retum-by-argument assignment could occur. The value
would therefore not be returned to the caller, and this error would have gone undetec-
ted until runtime. By contrast, a function taking a non-c 0 ns t pointer never permitted
user-defined conversion to occur; a type error would always have been detected at

33 strollstrup94, Section 3.7, p. 86.

Section 9.1.11 Pass Argument by Value, Reference, or Pointer 625

compile time. The latter is the desired behavior and is consistent with that of member
operators such as operatar=, which will not implicitly convert the object that they
modify (see Section 9.1.2).

It is worth noting that standard pointer conversions continue to work as expected when
passing the object to be modified via non-canst pointer. In other words, passing the
address of a derived object to a function taking a pointer to one of its public base classes
makes sense and the conversion will occur implicitly. It is only the unwanted, user-
defined conversion that is suppressed by requiring the client to pass the modifiable argu-
ment's address. Fortunately, most current compilers will at least warn you when a user-
defined conversion causes a temporary to be bound to a.non-constreference parameter.

The C language does not permit function arguments to be modified directly; C++
does. When first using C++, classic C programmers will often forget to insert the
con s t qualifier before a reference parameter where appropriate, leaving a reader to
wonder whether the function author intended the argument to be modifiable or not.
Discouraging any use of non-canst references in function arguments makes the intent
clear (or the defect immediately obvious).

Proponents of passing function arguments by modifiable reference would argue that a

reference is self-documenting in that there is no question about whether a valid object
must be supplied, whereas a pointer argument leaves this possibility open. Again, the
only way to know what is expected is to look at the header file for each function
called (and that could mean many header files).

Forcing the client to pass the address for a modifiable argument often requires the cli-
ent to type the extra keystroke "&". However, this extra keystroke is worth its weight
in gold when it comes to advertising that a function call can potentially modify its
argument. And because most functions do not modify their parameters, almost all
function calls can quickly be eliminated from suspicion.

Returning an argument by non-c a ns t pointer is a general and context-independent

technique; the syntactic anomaly alerts clients to the special nature of the argument.
Any notational convenience of passing a modifiable argument into a function by non-
con s t reference is outweighed by the need to avoid costly surprises. However, non-
can s t reference parameters continue to have their place in operator functions (e.g.,
operator+=) and well-entrenched idioms such as streams, which make no sense
unless the stream can be modified. The context of the stream idiom makes the semantics
626 Designing a Function Chapter 9

of their usage relatively clear, compared with returning some little-known object
through a modifiable reference.

Guideline

Avoid storing the address of any argument to a function in a location

that will persist after the function terminates; pass the address of the
argument instead.

Another related issue is that passing a user-defined type by con s t reference is so com-
mon that we might never suspect the importance of a particular value's being an
lvalue. Consider the scenario of Figure 9-22. An infinite precision integer type
my _B i gIn t is defined that can be constructed from a fundamental i nt type. The
my _B i gIn t Set is a homogeneous collection that stores only the address of the object
supplied to its add function. Suppose a naive user tries to create a function 9 that adds
three integers to the set. Each integer is implicitly converted to a temporary
my _B i gIn t, which is guaranteed to remain valid only until the function returns; the
temporary can be destroyed any time thereafter until exiting the scope in which the
temporary was created. 34 If the second temporary my _B i gIn t is no longer valid by the
time the i sMembe r method of my _B i 9 I ntSet is invoked, a memory reference through
a bad pointer value could easily cause this program to crash!

class my_Biglnt {
I I ...
public:
my _B i gIn t ( i nt i);
I I ...
};

class my_BiglntSet {
canst my_Biglnt **d_set_p;
int d_size; II physical size
int d_length; II cardinality

34 ellis, Section 12.2, p. 268.

Section 9.1.11 Pass Argument by Value, Reference, or Pointer 627

public:
I I ...
void add(const ni_Biglnt& bi); II bad idea: should pass by pointer
/1 Stores the address of this object in the set.

int isMember(const my_Biglnt& bi) const;

II Returns 1 if bi is a member of the set; else O.
};

void g()
{
my_BiglntSet set;
set.add(l); II Address of temporary my_Biglnt Added
set.add(2); II Address of temporary my_Biglnt Added
set.add(3); II Address of temporary my_Biglnt Added
set.isMember(2); II core dump?!

Figure 9-22: Retaining the Address of a Reference Argument in a Function

Without careful scrutiny of the class definitions, the client has absolutely no warning
that the address of the object (and not a copy of the object) will be retained. Had we
instead defined the a dd function of my _B i gIn tSet to take a con s t pointer, we would
have alerted the client that this function·considers the lvalue to be important, and-at
the same time-documented that fact directly in the declaration itself.35 The modified
usage model for my _B i gIn t 5e t is illustrated in Figure 9-23.

class my_BiglntSet {
I I ...
public:
I I ...
void add(const ni_Biglht *bi);
I I ...
};

void 9 ()
{
my_BiglntSet set;
set.add(l); II compile time error!
set.add(&2); II compile time error!
I I ...

Figure 9-23: Making the Need for an LvaIue Explicit

recommendation, called the Linton convention, is presented in murray, Section 9.2.4,

35 This
pp.213-215.
628 Designing a Function Chapter 9

Storing the address of an argument to a function is bad form. If the argument is passed
by value, it is represented- as a local automatic variable and the address will become
invalid as soon as the function returns. If the argument is passed by canst reference,
we have- no guarantee that it does not refer to a temporary. Passing the argument by
can s t pointer instead of by con s t reference suppresses the implicit creation of a tem-
porary, which is desired behavior when we plan to hold onto that address. Exceptions
to this guideline do occur in very common idioms when it is obvious from context
(e.g., an iterator) that the address of the object must be stored. Note that when a func-
tion stores the address of a oon- can s t argument for later modification, the two guide-
lines presented in this section (e.g., modifiable + lvalue) both apply; in this case, the
object should always be passed by non-canst pointer.

"........
. '.,. .'....', . ,.',.......
".
> .''''' ,,',.,'.,
" ............
,:"
".. _...._ i _. .....
_
.. . . . . . . . .
'" '

: .. :: : :.. ::~ . . .. .. ..,

..........

Never attempt to delete an object passed by reference.

Beyond modification, functions that delete an object should always take a non-canst
pointer to that object and never a non-canst reference. In order to delete an object,
you must supply a pointer to the delete operator. Taking the address of an object to be
deleted is error prone; some compilers (e.g., CFRONT) will generate a warning mes-
sage, cajoling the developer to add an extra assignment (or worse, a cast) to a pointer
variable. Even more compelling is the fact that the C++ language specification per-
mits the value of a deleted pointer to be adjusted (e.g., to 0) by the compiler. 36 A null
(or invalid) reference is not permitted in the language. 37

Using pointer instead of reference arguinents to capture the semantic properties men-
tioned in this section has yet another benefit in terms of maintenance. If a function
that previously did not modify or take the address of an argument should suddenly be
changed to do so, all clients of that function would be forced to examine their code
before they could recompile. This is exactly what we want! Making such significant
semantic changes with syntactic compatibility could silently lead to subtle bugs and
-very unpleasant surprises.

36 ellis,
Section 5.3.4, p. 63.
37 cargill, Chapter 6, p. 125; ellis, Section 8.4.3, p. 153.
Section 9.1.12 Pass Argument as canst or Non-canst 629

9.1.12 Pass Argument as canst or Non-canst

Whenever a pointer or reference passed to a function refers to the object as canst, it

widens the audience of potential clients who can take advantage of this function.

Guideline
Whenever a parameter passes its argument by reference or pointer to
a function that neither modifies that argument nor stores its writable
address, that parameter should be declared canst.

As a rule, whenever we can reasonably pass a pointer or reference argument as canst,

we should. 38

Guideline
Avoid declaring parameters passed by value to a function as canst.

An argument passed to a function by value is a copy. Declaring the parameter canst

makes its value immutable in the function body:

void f(const int i) II bad idea

{
I I ...
++i; II compile-time error
/ / ...
}

Whether or not this local copy is changed is an implementation detail of the function;
declaring it can s t exposes this decision in the interlace, compromising not only insu-
lation but also readability. This is not an issue for user-defined types since we never
pass them by value anyway (see Section 9.1.11).

38 See meyers, Items 21~22, pp. 73-82.

bJU Uesigning a !i'unction Chapter 9

Guideline
Consider placing parameters (except perhaps those with default
arguments) that enable modifiable access before parameters that
pass arguments by value, canst reference, or canst pointer.

Except for (optional) parameters with default arguments added after a function is
already in use, parameters that allow their arguments to be modified should precede
parameters whose arguments are passed by value, con s t reference, or con s t pointer.
Apart from making where to look for modifiable arguments more uniform, this rec-
ommendation is admittedly arbitrary; however, it is a classic style that is language
independent, predates C++ (and even C), and has proven useful over the years.

9.1.13 Friend or Non-Friend Function

Friendship, even within a single component, affects maintenance cost.

Avoiding unnecessary friendships (even within the same component)

can improve maintainability.

Before making an individual operator a friend, consider whether there is a primitive

member function that can be used to implement that operator. For example, we can
often implement free operator+ in terms of the primitive member operator+= (see
Section 3.6) without making ope ra to r+ a friend. Similarly, a single public member
function compa re can be used to implement all six of the free equality and relation oper-
ators (== != <= < >= » (see Section 9.1.2). Typically an iteratorclass with private
access can be used to implement a free output 0 per a tor << of a container type (such
as a set, list, etc.), obviating individual friendships and enhancing user extensibility.
Section 9.1.14 Inline or Non-Inline Function 631

Guideline
Avoid granting friendship to individual functions.

In general, whenever we decide we need a free operator, we should be cognizant of

what primitive functions we might use to implement that operator. Making a free
operator a friend could compromise encapsulation (see Section 3.6).

9.1.14 Inline or Non-Inline Function

From Section 6.2.3 we know that inline functions affect insulation. Apart from expos-
ing the implementation, large inline functions can increase executable size, poten-
tially making an integrated system run slower than if some of these functions had
been declared non-inline. If insulation is not an issue, the first question is whether the
object code resulting from the body of the function is larger or smaller than the non-
inline function call. If the inline object code is no bigger than a function call, inlining
will not increase executable size.

Guideline
Avoid declaring a function i n1i n e whose body produces object code
that is larger than the object code produced by the equivalent non-
inline function call itself.

For functions that merely get and set data members, it is often reasonable to use an
inline function without first acquiring performance data. For function bodies that gen-
erate more object code than the corresponding non-inline function call, performance
analysis at the system level should precede the decision to define the function inline.
Passing additional arguments to a function increases the amount of code generated for
a non-inline function call. Therefore, an inline function taking several arguments
could justify a somewhat larger function body before profiling.
632 Designing a Function Chapter 9

If a function is called frequently and performance is critical, the next question to ask
is, "From how many distinct locations can the function be called?" If access to the
function is restricted and the function is known to be called from only a few distinct
locations, then inlining is not likely to be an issue with respect to executable size. If
the function is large and may be called from many locations, the function is not likely
to be a candidate for inlining.

Guideline

Avoid declaring a function i n1i ne that your compiler will not

generate inline.

Finally, inlining is merely a hint to the compiler; there is no way to ensure that a func-
tion will actually be i n 1i n e' d. Whenever we take the address of a function declared
i n 1 i ne, we force a static (non-inline) version of the function to be generated in the
translation unit where the address was taken. If a function declared i n 1 i n e is too large
or too complex, it might not inline; the metrics that control this are compiler dependent.

When a function does not inline, the compiler defines a static version of the inline
function in each translation unit that uses the inline. These multiple static copies may
cause the executable to be bigger and run more slowly than if the function had been
declared non-inline. Fortunately, there are usually ways to ask a compiler to report
functions that do not inline. 39

A dynamically bound function call cannot be generated inline; however, a virtual

function call can be inlined when the virtual call mechanism is disabled by using the
scope resolution operator (: :). A virtual function call can also be inlined if the com-
piler can determine the exact type of the concrete object (e.g., when the function is
called from the object itself instead of through a pointer or reference). In any event,
the compiler will be forced to implement a non-inline version of the virtual function
in order to store its address in the virtual tables. If we are not careful, far more than
one static copy of this function could be generated (see Section 9.3.3).40

39 See meyers: Item 33, pp. 107-110.

40 See also murray, Section 9.13.2, p. 244.
"
Section 9.2 Fundamental Types Used in the Interface 633

9.2 Fundamental Types Used in the Interface

In Chapter 3 we discussed the uses relation in terms of user-defined types. In this sec-
tion we address the use of various fundamental types in the interface of a function.

9.2.1 Using short in the Interface

The C++ language requires that variables declared of type c ha r or s h 0 r t be promoted

automatically to type i nt before participating in an expression. That is, no direct use
of c ha r or s h0 r t values can be made in an expression apart from determining their
size (s i z e0 f) or taking their address (unary &).

Guideline
Avoid using short in the interface; use i nt instead.

Figure 9-24a illustrates that before a c ha r or ash 0 rt is used in a binary expression, it

is first automatically promoted to a temporary of type i nt. Irrespective of any over-
loaded function call resolution, the same automatic promotion to i n t values also
occurs implicitly during a function call as indicated in Figure 9-24b. The type i nt in
C++ typically corresponds to the fundamental integer size supported by the underly-
ing computer hardware. For most commercially available workstations, an i nt is (at
least) 32 bits.41

In what follows I am assuming a 32-bit (or larger) architecture. If you are working on a 16-bit
41
machine or an embedded system, some of the statements in this section will not apply.
634 Designing a Function Chapter 9

int f(char,int}; char c; short s;

f ( c , s )
char c; short s;

c + s
(int) t004 (int) tOOS

(int) t001 (int) t002

(int) t003 (int) t006

(a) Integral Promotion in Binary Operation (b) Integral Promotion in Function Call

Figure 9..24: Result of Integral Promotion

Figure 9-25 illustrates a class that uses short instead of i nt in its interface. Why
might we want to do such a thing? The motivation comes from a desire to express
intent directly in the declaration and avoid having to resort to comments. If we declare
that a parameter is ash 0 r t, no one would ever try to pass in anything larger and so we
don't have to check it ourselves, right?

class my_Point {
short d_x;
short d-y:

public:
II CREATORS
my_Point(short x, short y):
my_Point(const my_Point& p);
my_Pointe);

II MANIPULATORS
my_Point& operator=(const my_Point& p);
void x(short x);
v 0 i d y ( s hart y);

II ACCESSORS
short xC) canst:
short y() canst;
};

Figure 9-25: Using short Integers in the Interface (Bad Idea)

Section 9.2.1 Using s h 0 rt in the Interface 635

.I ... ~"i~Ciple 1
., ........... .

Specifying design decisions directly in the code instead of relying on

comments is a design goal; designing robust interfaces that are safe to
use and easy to maintain will occasionally compete with this goal.

The fact of the matter is that documenting information in the header file that is useful
only when looking directly at the header file itself can be of limited utility when it
comes to maintenance (see Section 9.1.11). Clients will pass an integer literal or
expression regardless of how we attempt to document it in the header; declaring the
integer to be ash a rt simply causes the truncation to occur outside the function rather
than inside, making it impossible for the function itself to detect an overflow error. To
the client, the perception is the same: the function doesn't work.

Consider the answers to the following questions:

1. Does using ash art in the interface ensure at compile time that overflow
will not occur at runtime?

No. The C++ language allows arithmetic overflow to occur silently at runtime.

2. Does using short in the interface allow for overflow detection?

No. If the interlace accepted an i nt, we could at least detect a coordinate

that is out of range of the implementation; at a minimum, passing an i nt
would allow us to assert the precondition.

3. Does using s h 0 r t in the interface serve to encapsulate or un -encapsulate

the implementation?

Exposing s h 0 r t in the interface limits the size of the coordinates that any
implementation can accommodate and eliminates our ability to detect
overflow; limiting implementation choice is a symptom of reducing
encapsulation.
636 Designing a Function Chapter 9

4. Does using s h 0 r t in the interface improve or degrade efficiency?

If anything, the argument may have to have its high-order bits masked
off, requiring additional work and therefore reducing runtime efficiency.

5. Does using short in the interface interfere with overloaded function

resolution?

Yes. According to the rules of the language, converting an i n t to ash 0 rt

is a standard conversion just like converting an i n t to ado ub1 e. That is,
if two functions were named f, one taking a short and the other taking a
doub 1 e, the call f ( 10) would be ambiguous.

6. Does using s hart in the interface interfere with template instantiation?

template<short N)
class pub_BitVec {
int d_bits : N;

public:
BitVec();
int operator[] (int i);
void set(int i);
void clear(int i);
void toggle(int i);
};

Figure 9-26: Template Class Parameterized by s h 0 r t

Yes. According to the rules of template instantiation, the type of a tem-

plate must match the argument exactly; a template parameterized by a
short such as pub_Bi tVec in Figure 9-26 will not be instantiated when
declared with an integer literal or any compile-time constant integral
•
expressIon:

BitVec<2> vI; II expecting short got int

BitVec(short(Z» vI; II ok.
BitVec<5 - 3> v2; II expecting short got int
BitVec<short(5 - 3) vI; II ok.
Section 9.2.2 Using un s i 9 ned in the Interface 637

9.2.2 Using uns i gned in the Interface

The C++ language requires that binary operators involving one un s i 9ned integer first
convert the other integer to un s i 9 ned before performing the operation. Usually this is
not a problem; however, when it is, it's not at all easy to debug.

Guideline
Avoid using uns i gned in the interface; use i nt instead.

#include <iostrearn.h> #include <iostream.h>

rna i n ( ) ma i n ( )
{ {
unsigned int i = 3; unsigned int i = 3;
co ut << "3 * -- 1 - " cout « "(3 > -1) = "
<< i * --1 << end 1 ; << (i > -1) << "end 1 ;
} }

II Output: II Output:
II john@john: a.out II john@john: a.out
II 3 * -1 = 4294967293 II (3 > -1) = 0;
II john@john: II john@john:
* -1 > -1

(unsigned) -1 (unsigned) -1

(unsigned) t007
/
(unsigned) tOOa

(a) Using un sign ed in (b) Using un s i 9 ned in

Arithmetic Expressions. Logical Expressions

Figure 9-27: Mixing i nt with un s i 9 ned in Binary Expressions

Figure 9-27a illustrates that when a signed and an uns i gned value are involved in
a binary operation, the bit pattern of the s i 9 n ed number is silently reinterpreted
as an un s i 9ned number. No actual temporary is created. For most integer repre-
sentations, the result is the largest number that will fit in an uns i gned (e.g.,
638 Designing a Function Chapter 9

2 32 - 1 = 4294967295). This number is then multiplied by 3, which causes the

32
unsigned to overflow; the result is therefore printed as (3 • (2 _1» mod 2 32 =
2 32 _,3. In Figure 9-27b precisely the same reasoning applies. The unsigned value
again causes the bit pattern of the sign ed value to be reinterpreted to a huge un signed
value, the comparison is made, and-for many-produces unexpected results.

class my_Array {
int *d_array_p;
unsigned short d_size; II bad idea: Short used in implementation
II only, but see Section 10.1.2.
public:
II CREATORS
ArrayCunsigned int size);
Array(const Array& array);
,...,Array();

II MANIPULATORS
Array& operator=Cconst Array& array);
int& operator[](unsigned int i);

/1 ACCESSORS
int operator[]Cunsigned int i) canst;
unsigned int sizeC) canst;
};

Figure 9-28: Using unsi gned Integers in the Interface (Bad Idea)

One might argue that we deserve what we get when we mix negative and unsigned
integers. Perhaps-when we do it. But consider the seemingly innocent my~Array
class shown in Figure 9-28.

#include <assert.h>
#include <iostream.h>
void printForwardMovingAverageCconst my_Array& a, int width)
{
assertCwidth > 0);
canst int N = width - 1;
int total = 0;
for (int i = -N; i < a.sizeC); ++i) {
if (i + N < a.size(» {
total += a[i + NJ:
}
cout « i « '\t' « doubleCtotal)/width « endl;
if C i >= 0) {
total -= a[i];
}
}

Figure 9-29: Innocent Client Function to Print the Forward Moving Average
Section 9.2.2 Using uns i gned in the Interface 639

As a client of the my_Array class, I have written the function shown in Figure 9-29,
which takes an instance of my_Array and prints its forward moving average of speci-
fied width. As a responsible developer, I whipped up the little test driver shown in
Figure 9-30 to verify that my function worked-and it did not.

II test.c
# include <stdlib.h> II atai()

main(int argc, char *argv[])

{
canst int SIZE = argc > 1 ? atoiCargv[l]) : 4;
canst int WINDOW = argc > 2 ? ataiCargv[2]) : 2;
my_Arrayarray(SIZE):
for (int i = 0; i < SIZE; ++i) {
array[i] = 1:
}
printForwardMovingAverage(array, WINDOW);
}

Figure 9-30: Test Driver for pri ntForwa rdMovi ngAverage Function

The output I expected for the default values (an array of S I ZE 4 containing alII' sand
a WIN DOW width of 2) was supposed to look as shown in Figure 9-31a; the disappointing
reality is shown in Figure 9-31b.

john@john: a.out . john@john: a.out

-1 0.5 john@john:
o 1
1 1
2 1
3 0.5
john@john:

(a) Expected Output (b) Actual Output

Figure 9-31: Driver Output for pri ntForwa rdMovi ngAverage Function

Even though we know better than to mix uns i gned and i nt, one does not always
check a header for each integer value that is returned. In this case, it was s i z e ( ) that
did us in. The problem is again that comparing a negative number with an unsi gned
i nt will usually go the wrong way, as illustrated again in Figure 9-32.
640 Designing a Function Chapter 9

#include <iostream.h>
rna i n ( )
{
my _A r ray a ( 10 ) ;
cout « "size = II « a.size() « endl;
if (a.size() > -1) {
cout « IIsize is positive or zero." « endl;
}
else {
cout « "size 1S negative!!!" « endl;
}
}

II Output:
II john@john: a.out
II size = 10
II size is negative!!!
II john@john:

Figure 9-32: Comparing an uns; gned i nt Return Value Against a Negative i nt Value

All we need to do to repair the damage in this case is to replace the line

for (i nt i = - N; i < a. s i z e ( ); ++ i) {

in Figure 9-29 with the pair of lines

canst int S = a.sizeC); II work-around for returning unsigned

for (int i = -N; i < S; ++i) {

and the function will operate correctly.

Occasionally comments work better than trying to express an inter-

face decision directly in the code (e.g., uns i gned).

Bugs occurring from the use of uns i gned in the interface are frustrating and notoriously
hard to detect. Looking at the problem with a debugger, it can seem that the i f state..
ment itself in Figure 9-32 must be broken. It is often quite a stretch to guess that the
return value of the function is declared un s i 9 ned and is implicitly converting some
other negative number to a positive value as a result of a binary comparison operation.
Section 9.2.2 Using uns i gned in the Interface 641

Consider the answers to the following questions:

1. Does using uns i gned in the interface ensure at compile time that negative
numbers will not be passed in at runtime?

No. The C++ language allows the bit pattern to be reinterpreted silently at
runtime.

2. Does using un s i 9ned in the interface allow for the possibility of checking
for negative values?

Yes, but you have to coerce the uns i gned back to an i nt internally.

·3. Does using un s i 9 ned improve or degrade runtime efficiency?

It typically has no effect.

4. Does using uns i gned increase the size of the positive integer that can be
stored?

Yes-by 1 bit. This extra bit is rarely useful. If the extra capacity is
needed, there is a risk of losing data when the un s i 9 ned is converted back
to an i nt (see Section 10.1.2).

5. Does using un s i 9 ned in the interface increase or decrease the likelihood

of user error?

It increases it. Without looking at the header file, there is no safety advan-
tage, since the conversion is done silently. Naively using an unsigned
return value in an expression that involves a negative i nt value will cause
the client's code to break at runtime.

6. Does using un s i 9 ned in the interface serve to encapsulate or unencapsu-

late the implementation?

Exposing unsigned in the interface effectively limits the values that any
implementation will accommodate, thereby reducing encapSUlation.

7. Does using uns i gned in the interface interfere with overloaded function
642 Designing a Function Chapter 9

resolution?

Yes. According to the rules of the language, converting an i nt to an

uns i gned is a standard conversion, just like converting an i nt to a
do U b1e. That is, if two functions were named f, one taking an un s i 9ned
and the other taking a doubl e, the call f( 10) would be ambiguous.

8. Does using un s i 9 ned in the interface interfere with template instantiation?

Yes. We encounter a problem for precisely the same reason as when

parameterizing a template with a short (see Section 9.2.1).

9.2.3 Using long in the Interface

Although in this book we cavalierly assume that an i nt holds at least 32 bits, in fact
only 16 bits are needed to satisfy the ANSI requirement for type i nt.42 If you are
working on a 16-bit machine, the following guideline clearly does not apply.

Guideline
Avoid using long in the interface; assert( 5 i zeaf( i nt) )== 4) and use
either i nt or a user-defined large-integer type instead.

The c++ language defines along integer to be at least as large as an i nt. Along i nt
means "the biggest integer you have"; an i nt means "the biggest integer that is effi-
cient" (typically the natural word size of the computer). On a 16-bit machine, along
is probably a double word (32 bits). On most commercially available compilers for
32-bit workstations, along is a single 32-bit word. On 64-bit architectures, an i nt
will probably continue to be set at 32 bits for compatibility with existing programs,
while a 10 n9 might be 64 bits. If portability is an issue, any assumption that a 10 ngin t
is more than 32 bits is a recipe for failure (not every machine you may want to port to
will have a 64-bit long i nt).

42 ellis, Section 3.2.1c, p. 28.

Section 9.2.3 Using 1 0 n 9 in the Interface 643

Figure 9-33 illustrates a component that uses 1 0 ngin t instead of i n t in the interface.
Why might we want to do such a thing? Usually the answer to this question is some-
thing like, "1 want it to hold the biggest integers it can." For small projects on small
machines, this reason might be sufficient. For large projects running on industrial-
strength workstations on multiple platforms, the i nt is either big enough or it isn't-
if you're not sure, then it isn't. Fortunately, the C++ language enables us to define a
larger integer type ourselves.

class my_Point {
long int d_x;
10 ngin t d_y;
public:
II CREATORS
my_Point(long int x, long int y);
my_Point(const my_Point& p);
my_Pointe) ;
II MANIPULATORS
my_Point& operator=(const my_Point& p);
void x(long int x);
void yClong int y);
II ACCESSORS
long int xC) canst;
long int y() const;
}:

Figure 9-33: Using long Integers in the Interface

Whenever we initialize, assign, or pass along i nt value where an i nt value is expected,

we are forcing a standard conversion that has the potential to lose information (if it didn't,
there would be no reason to use long in the first place). The compiler may warn clients of
these "lossy" conversions, as illustrated in Figure 9-34. We could always tell our clients
how to suppress these warnings by sprinkling their code with casts-just kidding!

int r(int x, int y);

void g()
{
my_Point p(3, 2); II fine, int converted to long ..
int j. i - p.x(): II warning: long assigned to int
j = p.y(); /1 warning: long assigned to int
double d =r(p.x(), p.y(»; II warning: argument 1: long passed as int
II warning: argument 1: long passed as int
}

Figure 9-34: Mixing Types i nt and long

644 Designing a Function Chapter 9

Consider the answers to the following questions:

1. Does using along in the interface ensure increased capacity over an i nt?

Not on all platfonns. Often an i nt and along are the same size. If you
depend on increased capacity, your code will not be portable.

2. Does using long in the interface hinder usability?

Yes. A potentially large number of warning messages could inundate clients

(see also question 3).

3. Does using long in the interface interfere with overloaded function reso-
lution?

Yes. According to the rules of the language, converting an i nt to along

is a standard conversion, just like converting an i nt to a do u b 1e. 43 That
is, if two functions were named f, one taking along and the other taking
a do ub 1e, the call f ( 10) would be ambiguous.

4. Does using long in the interface interfere with template instantiation?

Yes. We encounter a problem for precisely the same reason as when

parameterizing a template with a short (see Section 9.2.1).

9.2.4 Using float, doubl e, and long doubl e in the Interface

The C++ language enables floating-point computation to occur in each of the three
floating-point types:

• float,
• double, and
• long double.

43 Going from i nt to long is not an integral promotion; rather it is a standard conversion. Converting
an i nt to along and its (canst/val at; 1e) equivalents is the only "non-lossy" standard conversion in
the language.
Section 9.3 Special-Case Functions 645

Guideline
Consider using do U b1e exclusively for floating-point types used in the
interface unless there is a compelling reason to use float or 1 ang
daubl e.

Historically, C required all floating -point expressions to be of type do ub 1 e and did not
support long doubl e. ANSI C introduced the ability to do arithmetic directly with
float values. Most C library calls pass and return a floating-point value as a daubl e.
These days, much of the computer hardware is optimized to make daubl e floating-
point calculations run as quickly as possible. In fact, a double precision multiply on
my machine is an order of magnitude faster than an integer multiply (which is imple-
mented as a subroutine).

. J:'~fipl~·• • ·•·•· ·.
I
·
•· .·.·•· .•· ·.·•·.·.· .····.··.···...........

..
...... ........ ...... ... ... ... . . . . . . . . . . . ' .. ·.'····1.·
.

In most cases that arise in practice, the only fundamental types you
need in order to represent integer and floating-point numbers in the
interface are i nt and do Ub1e, respectively.

The same issues of consistency, error checking, operator overloading, and template
instantiation that applied to the integer types apply to floating-point types as well.

9.3 Special-Case Functions

There are a few special member functions that warrant some discussion. Conversion
operators (i.e., single-argument constructors and "cast" operators) and compiler-gen-
erated functions (such as the copy constructor, the assignment operator, and, in partic-
ular, the destructor) deserve specific mention.
646 Designing a Function Chapter 9

9.3.1 Conversion Operators

Implicit conversions compete with type safety, can introduce ambiguities, -and in gen-
eral increase the cost of maintaining a program. Any time we create a constructor that
can take a single argument, we enable an implicit user-defined conversion. Defining a
conversion operator other than a constructor, referred to in this book as a cast
operator, also enables implicit conversion. An example of each of these forms can be
found in Figure 9-35.

pub_String {
I I ...
public:
pub_String(const char *cptrt int maxSizeHint = 0); II "cast constructor"
I I ...
operator const char *() canst; II "cast operator"
};

Figure 9-35: The 1\vo Forms of User-Defined Conversion Operators in C++

Constructors that enable implicit conversion, especially from widely

used or fundamental types (e.g., i nt), erode the safety afforded by
strong typing.

A constructor accepting a single argument, sometimes called a cast constructor, can

contribute to surprises by enabling an unexpected conversion. Consider the two-
dimensional table component sketched in Figure 9-36.

II d2_table.h
# ifndef INCLUDED_D2_TABLE
# define INCLUDED - 02 - TABLE
class d2_Entry;
class d2_Rowlter;
class d2_Collter;
Section 9.3.1 Conversion Operators 647

class d2 Table {
// ...
friend d2_Rowlter:
// ...
public:
d2_Table();
// ...
}:

class d2_Rowlter {
// ...
friend d2_Collter;
// ...
public: .
d2_RowIter(const d2_Table& table): II takes a d2_Table
operator const void *() canst;
void operatar++();
};

class d2 Col Iter {

I I ...
public:
d2_ColIter(const d2_Rowlter&); II takes a d2_Rowlter!!!
operator canst void *() const;
void operator++();
const d2_Entry& aperator()() const;
};

#endif;

Figure 9-36: Sketch of Two-Dimensional d2_tabl e Component

The intent is that a client will apply a row iterator to the table and, for each row position,
reapply a new column iterator to that row iterator.

As the function in Figure 9-37 -shows, editor cut-and-paste can introduce bugs:
c; t ( t) on the indicated line should have been cit ( r it). As long as our code is
"type-safe," we stand a good change of detecting such bugs at compile time-but not
here! What actually happens is that each instantiation of the second iterator forces an
implicit conversion of the d2_ Tab 1e, t, to an unnamed temporary of type d2_Row I te r
(which happens to be positioned at the first row of the table). There is no guarantee that
this temporary row iterator will remain valid while the column iterator operates; but if
it does, the table will appear as if the contents of all rows are identical to the fITst.
648 Designing a Function Chapter 9

void g(d2~Table& t)
{
for (d2~Rowlter rit(t); rit; ++rit) {
for (d2_Collter cit(t); cit; ++cit) ( II <-- oops!!! "cit(t)"
II should be "cit(rit)"
cout « cit() « endl; II print (ith row, jth col) table entry
}
}
}

Figure 9-37: (Mis)using the d2_tab 1 e Component

A cast constructor taking a user-defined type is less likely to be a problem in practice

than constructors taking a single fundamental type-especially an integral type. For
example, consider the situation depicted in Figure 9-38. A gr _Graph provides its cli-
ents with the ability to look up a particular node either by name or ide Unfortunately, a
9 r _N 0 del d knows how to construct itself from an arbitrary integer. The apparent type
safety afforded by gr _Graph's overloaded 1 ookupNode methods does little to detect
the error in function f. The problem is that the extra "*" at the indicated line turns the
character string name, n am e s [ aJ, into the ASCII value of its first character; this value
is promoted to an i nt and then implicitly converted to some bogus gr _Nodeld. It is
anyone's guess what happens next. The error would have been detected at compile
time had gr _Nodeld not enabled an implicit conversion from an integral type. (A sim-
ilar problem results from the use of default arguments in Figure 9-18b.)

class gr_Node;

class gr_Nodeld {
int d_index;

public:
II gr_Nodeld(int index); II there goes type safety
I I ...
};

class gr_Graph {
I I ...
public:
I I ...
const *lookupNode (const char *name) const;
gr~Node
II lookup a node in the graph by name
const gr_Node *lookupNode (const gr_Nodeld& id) const;
II lookup a node in the graph by id
};
Section 9.3.1 Conversion Operators 649

void f(const char *names[], const gr_Graph& g)

{
const gr_Node *node = g.lookupNode(*names[O]); II <-- oops!!! didn't
II want * in *names[O]
if (node) {
cout « *node « endl; I I all is well, pri nt the node
}
else {
cout « "Program Error: What happened to the node!!!" « endl;
assert(O); II node with this name should be there
}
}

Figure 9-38: (Mis)using gr _Graph to Look Up a gr _Node by Name

Guideline
Consider avoiding "cast" operators, especially to fundamental
integral types; instead, make the conversion explicit.

In general, explicit conversion functions are more readable and much safer than
implicit conversions. Although cast constructors are a necessary part of doing busi-
ness, cast operators are a form of implicit conversion that is more easily avoided: we
can always supply an explicit conversion function to do the work of a cast operator.

As we saw in Figure 9-6, providing p ub_S t r i n g with both a cast constructor and a
cast operator (for implicit conversion to and from a can s t c ha r *) led to ambiguities
that required further effort to resolve. Had we replaced the cast operator with a mem-
ber function such as con s t c ha r * s t r () con s t; with the identical implementation,
no ambiguity would have occurred. 44

In very limited, well-understood situations, implicit conversions can increase usabil-

ity.45 Automatically converting a pub_String to a canst char * and converting an
arbitrary object to a canst vaid * (as a test for validity) seem to be reasonably safe
uses of implicit conversion. Arguably, the client code would be clearer if forced to call
explicit members such as s t r ( ) and i s Val i d ( ). What makes these conversions rea-

44 See meyers, Item 26, p. 89.

45 See strollstrup, Section 7.3.2, pp. 232-233.
650 Designing' a Function Chapter 9

sonable is the lack of surprise potential. Passing a pub_St ri ng to a function expecting

a con s t c ha r * is almost always a reasonable thing to do because the semantics of the
two types are so tightly coupled. Implicitly converting to a can 5 t va i d * is safe
because the only useful thing you can do with the result is compare it to O.

Clear misuses of implicit conversion involve converting an object to an unrelated or

more widely usable type--especially a fundamental type. For example, having a spe-
cific object such as 9 r _N ad e I d convert itself to an i n t representing its internal index
is entirely inappropriate and virtually eliminates any type-safety advantage of having
represented the value as a class. A geom_Poi nt that knows how to convert itself to a
double representing its magnitude would also be inappropriate, especially since
explicit conversion (e.g., using pt. magn i tude ( ) is safer, is more readable, and is an
interface alternative that is always available.

9.3.2 Compiler-Generated Value Semantics

The C++ language requires that the compiler automatically generate the definitions of
certain basic member functions, if needed, unless they are already explicitly declared
in the class (see Section 6.2.6). Most commonly of interest are the generated copy
constructor and assignment operator.

Guideline
Explicitly declare (either public or private) the constructor and
assignment operator for any class defined in a header file, even when
the default implementations are adequate.

When considering whether or not to declare a copy constructor or assignment opera-

tor explicitly, the first question to ask is whether we intend this object to support value
semantics (see Section 5.9). For some objects, such as Gnode in Figure 5-81, value
semantics do not make sense. For other objects, such as iterators, value semantics
make sense but are often not necessary for a sufficient interface (see Section 8.2). In
either case, we should explicitly inhibit the use of such value-semantic functions by
declaring them p r i va te and deliberately leaving them undefined. 46
Section 9.3.3 The Destructor 651

If value semantics are to be supported, the next issue is whether the compiler-gener-
ated constructor and/or assignment operator would do the right thing. 47 If the default
definitions are not correct, we will need to declare these members and define them our-
selves. Otherwise, we must determine the likelihood that the default definitions might
become invalid, and determine also the cost to our clients of making an uninsulated
change to our interface if they do. If the expected cost is too high, we would again opt
to define these operations ourselves rather than use the default implementation.

Finally, for very local objects where the compiler-generated implementations make
sense and insulation is not an issue, we might allow these function definitions to
default. In particular, allowing default copy and assignment semantics is often appro-
priate for classes defined entirely within a . c file. However some clients of an
exported class definition that relies on default semantics may be left with this nagging
doubt: is the default implementation really good enough, or did the author simply fail
to address this issue?

Note that some current implementations of C++ do not allow generated operator= to
be called via function notation, nor its address to be taken, as required by the lan-
guage. 48 Such failings by compilers bolster the argument in favor of always declaring
an exposed class's value-semantic operators explicitly.

9.3.3 The Destructor

The destructor is an important function with many unique responsibilities; we enu-

merate them here.

In every class that declares or is derived from a class that declares a

virtual function, explicitly declare the destructor as the first virtual
function in the class and define it out of line.

46 meyers, Item 27, pp. 92-93.

47 ellis, Section 12.8, p. 295; and meyers, Item 11, pp. 34-37.
48 ellis, Section 12.8, p. 296.
652 Designing a Function Chapter 9

The destructor is responsible for destroying the object and freeing any resources (e.g.,
dynamic memory) currently managed by that object. When a class declares a function
vir t ua 1, it is advertising itself as a base class-what other reason could there be for
declaring a function vir t u a 1? Derived classes may accrue resources even when the
base class has none. Conversely, in order to ensure that the derived class destructor is
called, even from a base-class pointer or reference, the base-class destructor must be
declared vi rtua 1.49

In an efficient implementation of dynamic binding, we would hope that there would

be only a single copy of any virtual table in the entire program. The question is, "In
which unique translation unit will the compiler deposit the virtual table definition(s)
for a given class?" The trick employed by CFRONT (and many other C++ implementa-
tions) is to place the external virtual tables in the translation unit that defines the lexi-
cally first non-inline virtual function that appears in the class (if one exists).

The cost of ignorance can sometimes be truly staggering. Figure 9-39 depicts a real-
life problem that went undetected in a large project for quite some time. The story
begins with the fact that the popular core_Stri ng class is derived from
cor e_S t r i n 9 Bas e that contains virtual functions, including of course a virtual
destructor. The cor e_S t r i n9 class, not allocating any additional resources, faile,d to
declare a destructor at all. ~e compiler is required to generate a destructor for the
derived class and place it in a virtual table for the derived class.

class core_StringBase {
I I ...
public:
I / ...
virtual ~core_StringBase();
/ / ...
virtual int length():
virtual operator const char *() const;
};

class core_String: public core_StringBase {

int d_length;

49 ellis, Section 12.4, p. 278.

Section 9.3.3 The Destructor 653

public:
core_String(const char *cptr);
core_String(const core_String& string);
core_String& operator=(const core_String& string);
int length() { /* ... */ }
};

Figure 9-39: Failing to Define at Least One Virtual Function Out of Line

Not being given any clue as to where to place a unique global copy of the virtual table,
the compiler placed a copy of the table in every translation unit that included the
core_Stri ng header. To add insult to injury, there was also no unique place to gener-
ate a non-inline version of the destructor; hence, a static copy of the destructor was
placed in every translation unit along with the virtual tables. Finally, every inline vir-
tual function (e.g., 1 ength) was also denied a unique home for its out-of-line imple-
mentation. A static version of each inline virtual function was also placed in every
translation unit that included the cor e_S t r i n9 class.

The problem was finally detected when the Unix "nm" utility was run on the execut-
able and a histogram of static names turned up thousands of static function defini-
tions, each with the same name, but defined in separate translation units. Declaring
the destructor for cor e_S t r i n9 and implementing it out of line solved all of the prob-
lems. This behavior is cryptic and implementation dependent; however, this is our
current reality.

In the style we have followed throughout this book, creators precede any other non-
static member functions. Thus, the first virtual member function encountered is
invariably the destructor. Also, in order for the address of a destructor to be placed in
a virtual function table, there must be at least one version of the destructor defined out
of line anyway. The requirement that there must be at least one virtual function
declared non-inline, coupled with the natural lexical position of the destructor within
the class, makes the destructor the natural choice to be declared virtual and defined
out of line.

In rare cases (e.g., a deep inheritance hierarchy), performance may be improved by

defining empty destructors inline, in which case some other function in the class must
be declared a virtual, non-inline function to avoid generating redundant tables.
654 Designing a Function Chapter 9

Guideline
In classes that do not otherwise declare virtual functions, explicitly
declare the destructor as non-virtual and define it appropriately
(either inline or out-of-line).

For classes that do not otherwise declare virtual functions, implementing a virtual
destructor is not likely to be appropriate. Making the destructor alone virtual would,
in most implementations, increase the size of each instance by the size of a pointer.
For small objects such as geom_Poi nt, the increase in cost could be 50 percent. One
solution for guarding against memory leaks is that a class derived from a base class
with a non-virtual destructor should avoid managing additional resources that must be
released when the object is destroyed. 5o

For classes that do not require virtual functions, there is still a reason to require that
the destructor be declared explicitly. Calling the destructor of a fundamental type
explicitly is legal C++: 51

int i;
i. int: :----int(); / / 1ega 1 c++ ; doe s not h i n9

Attempting an explicit call to the destructor of an object that does not explicitly
declare one and for which none has been generated doesn't work on several current
compilers. Since it is not possible to take the address of a destructor, a destructor is
generated for a class that does not explicitly declare one only when a base class or
embedded member object has a destructor. 52 This fact has implications for template-
based container objects that attempt to call the destructor of the parameterized type
explicitly (Figure lO-33b provides a useful workaround). For consistency, it should be
possible to destroy any object in place, regardless of whether or not a destructor has
been defined.

50 meyers, Item 14, pp. 42-48.

51 ellis, Section 12.4, p. 280.
52 ellis, Section 12.4, p. 277.
Section 9.4 Summary 655

9.4 Summary.

c++ provides an enormous amount of flexibility in describing the function-level

interface. There are at least 14 separate questions we must address as we design each
function. Each of these decisions evokes additional considerations that must be
resolved in context:

1. Operator or non-operator function?

Operator:
• The operator notation improves usability (readability in
particular).
Non-Operator:
• The operation on the user-defined type does not
syntactically mirror the same operation on the fundamental
types.

2. Free or member operator?

Free:
• We want to enable implicit user-defined conversion for its .
leftmost argument.
• It is syntactically symmetric (e.g., -- < +).

Member:
• We want to disable implicit user-defined conversion for its
leftmost argument.
• It modifies an argument (e.g., = += *= ++).
• The language requires membership (e.g., ( ) [J -»).

3. Virtual or non-virtual function?

Virtual:
• Its behavior must be able to be overridden in a derived class.
Non-virtual:
• It is a symmetric operator function (e.g., ! = )= I).
• It is a unary operator function that should support user-
defined conversion of its argument (e.g.,! + -).
• Its behavior can be implemented as variation in the value of
member data.
656 Designing a Function Chapter 9

4. Pure or non-pure virtual member function?

Pure:
• Not overriding its behavior in a derived class is likely to be
an error.
• Physically decoupling the interface from the implementa-
tion is important.
• The class will be used by many clients.
• The class defines a protocol.
Non-pure:
• Default behavior'makes sense.
• Its default behavior is correct in many cases.
• The class will not be widely used.

5. Static or non-static member function?

Static:
• It uses a s t r uc t solely to scope the name of the function.
• It implements non-primitive behavior.escalated from a
.lower-level object
• Symmetry with respect to user-defined conversion is
needed among all of its arguments.

Non-Static:
• It depends on data contained within a specific instance of
the class.
• It is an operator function.

6. canst or non-canst member function?

canst:
• It does not modify bits embedded in the c 1 ass or
struct.
• It modifies only physical values that are never
programmatically accessible by clients.
Non-canst:
• It modifies logical values, even though the compiler says
can s t would be legal.
• It returns a non-canst version of a type that could violate
can s t-correctness.
Section 9.4 Summary 657

• It is static.

7. Public, protected, or private member function?

Public:
• It is intended for direct use by the general pUblic.
Protected:
• It is intended for use only by derived-class authors.
Private:
• It is a non-virtual implementation detail (especially to
factor the implementation of a public inline function).
• It is a virtual function that must be programmed but that
need not be accessed by derived classes.

8. Return by value, reference, or pointer?

Value:
• There is no preexisting object available to return.
• Preserving total encapsulation, is important.
Reference:
• There is always something to return.
• We are returning access to a polymorphic object whose
memory is managed elsewhere.
Pointer:
• There may be something to return.
• The function may fail.
Argument:
• We want to return a newly allocated polymorphic object in
a handle that will manage the object, reducing the like-
lihood of memory leaks.
• We want to preserve total encapsulation while returning
heavy-weight objects more efficiently than by value.
• We want to return more than one item.
• Both status and a value must be returned.

9. Return canst or non-canst?

Const:
• We are returning a pointer or reference to a data member of
the class.
658 Designing a Function Chapter 9

• Returning non-canst would violate canst-correctness.

• We are returning a reference to a shared dummy object
(e.g., a zero entry in a sparse array).
Non-canst:
• We are returning by value.
• We are providing direct writable access to a contained
object (e.g., in an array).

10. Argument optional or required?

Optional:
• We have added a new argument to existing code.
• There is a single algorithm.
• We want our code to be self-documenting .
.• The default argument is an invalid value.
Required:
• This is a widely used interface.
• The default value is a user-defined type.
• Insulation is important.

11. Pass argument by value, reference, or pointer?

Value:
• It is a fundamental or enumerated type.
Reference:
• It is a user-defined type that is not modified.
Pointer:
• It is modified.
• Its address is taken.
• It is deleted.
• It may be omitted.

12. Pass argument as canst or non-canst?

can s t:
• It is a user-defined type passed by reference.
• It is never modified, but is passed by pointer
(because a null value is sometimes appropriate).
Non-canst:
• It (e.g., an enumeration or fundamental type) is
Section 9.4 Summary 659

passed by value.

13. Friend or non-friend function?

Friend:
• Enforcement of encapsulation is not an issue (rare).
Non-friend:
• There is a member function (e.g., compa re) or friend class
(e.g., St ac kIt e r) available that is suitable for implement-
ing it (e.g., operator==).

14. Inline or non-inline function?

Inline:
• The size of the inline function body would be smaller
than the size of the non-inline function call.
• Performance is measurably critical, and it is
reasonably small or called from only a few places.
Non-inline:
• It will not inline.
• It is useful only when dynamically bound.
• Insulation is important.

There are many alternative integral types available for use in the interface of func-
tions: short, uns i gned, long, etc. In practice, on a 32-bit machine, the only integral
type we need in the interface is i nt. Using any other type is potentially inefficient,
unencapsulating, error prone, or just plain annoying to use.

There are three alternative floating-point types available in c++: float, doubl e, and
long doub 1e. Traditionally all floating-point arguments in C were converted to doub 1e
before being passed as arguments. Most hardware is geared to handle do Ub1e values
as efficiently as possible. Unless there is a compelling reason to do otherwise, all
floating-point numbers should be expressed as do Ub1 e in the interface.

Conversion operators (e.g., single-argument constructors and cast operators) compete

with compile-time type safety. Constructors that take a single argument enable
implicit user-defined conversion. However, such constructs are a necessary part of
many interfaces. On the other hand, cast operators are easily avoided, simply by pro-
viding explicit conversion functions. Occasionally usability is enhanced by implicit
660 Designing a Function Chapter 9

conversion. In most cases, however, implicit conversion is a liability, particularly

when it involves a fundamental integral type.

The c++ compiler automatically generates certain undefined functions (if needed).
There are a variety of reasons for not relying on the default behavior, particularly
when the interface is used widely throughout the system. Many implementations of
C++ depend on there being at least one virtual function defined out of line. In OUf
style, this will always be the destructor. Some current compilers do not allow explicit
calls to destructors that are not explicitly declared. In practice, it is wise to define the
destructor of every class explicitly. For classes with no virtual functions, define the
destructor inline or out of line as appropriate. For classes with virtual functions,
define the destructor out of line. For protocol classes (see Section 6.4.1.) the destruc-
tor should be empty.
 Implementing an Object

The cavernous realm of object implementation alternatives is made ever more vast by
good (Le., small, encapsulating) interfaces. Making a design error here is far less
costly than errors at higher levels of design because the problem is confined to a tiny
portion of the overall system. Yet there are still several ways in which even individual
implementation techniques can combine during system integration to affect the over-
all success of a project.

A program must run in an environment with finite resource (e.g., memory). Classes
with many instances active at a single time put a premium on the size of their objects.
The sizes and order of their individual data members will affect this size. Custom
memory-management techniques can sometimes be used to double runtime perfor-
mance, but they can also cause a system, over time, to soak up much more memory
than is actually necessary.

In this final chapter, we examine some basic principles relating to the organizational
details of implementing classes in C++. We even proffer some suggestions on imple-
menting individual member functions. In the remainder of the chapter, we examine
several issues relating to custom memory management.

Although memory management is a complex topic, it is a necessary concern of most

high-performance systems. We look at several detailed examples and experiments that
compare the relative merits of some common memory-management organizations. In
particular, we explore the performance advantages of class-specific management tech-
niques, and then discuss potential problems that can be caused when classes using
662 Implementing an Object Chapter 10

these techniques are integrated into larger systems. We then present object-specific
memory management as a preferred altemative~ne that avoids many of these prob-
lems while achieving essentially the same runtime performance as the class-based tech-
nique. Finally we discuss memory management in the context of templates, and provide
a detailed example of how to implement truly general-purpose container objects.

10.1 Member Data

In this section we discuss logical and organizational issues pertaining to the choice
and ordering of data members within a class.

10.1.1 Natural Alignment

Many common RISe-based microprocessors depend on instances of fundamental

types being naturally aligned. Being naturally aligned means that instances of built-in
types such as i nt, daub 1 e, and cha r * cannot reside at just any address, but instead
must be aligned on an N-byte address boundary where N is the size of the object.

DEFINITION: An instance of a fundamental type is naturally

aligned if its size divides the numerical value of its address.

Since s i z e a f ( c ha r) is 1, a c ha r may be stored at any addressable location in mem-

ory. If s i z e a f ( s hart) is 2, it cannot be stored at an "odd" address; instead it must be
stored at an "even" address, sometimes referred to as a half-word boundary (on a 32-
bit machine). Integers and pointers, which often have sizes corresponding to the word
size of the computer, would have to be stored at a word boundary (e.g., a 4-byte
boundary on a 32-bit machine). A daubl e, which is often larger than the word size of
a machine, would normally be stored on a two-word boundary.1

1 Oftena daubl e can be stored on an odd-word boundary (as opposed to an even-word boundary)
without disastrous consequences. However, on some architectures, failing to follow natural align-
ment for a daub 1e can result in a significant decrease in performance.
Section 10.1.1 Natural Alignment 663

DEFINITION: An instance of an aggregate type is naturally aligned

if the alignment of the subtype with the most restrictive alignment
requirement divides the address of the aggregate.

An instance of an array of a given type has the same alignment requirement as that of
the type itself. Satisfying natural alignment for a user-defined type means satisfying
the alignment requirements of the most restrictive embedded subtype. Figure 10-1
gives some examples of natural alignment on a typical 32-bit machine.

*) = s i z e 0 f ( i nt) =4 and s i z eo f ( do Ub 1e) =8.

struct A { struct B { struct C {

char d- c·, char d_c; double d- d·,
}; char d_ac[3]; char *d_pc_p;
};
.
int d- 1 ,•
};

sizeof(A): 1 sizeof(B): 4 sizeof(C): 16

alignment(A): 1 alignment(B): 1 alignment(C): 8

Figure 10-1: Size and Natural Alignment of Various User-Defined ~pes

The order in which data members are declared can affect object size.

The C++ language guarantees that in the absence of intervening access specifiers
(e.g., publ i c, protected, and pri vate), the memory for non-static data members
will be allocated with increasing address values corresponding to their order of decla-
ration within the structure; however, they need not be contiguous. 2 Alignment within

2 eni~_ Section 9.2. D. 173.

664 Implementing an Object Chapter 10

a structure can cause gaps at both the middle and end of a structure (but never at the
beginning). As a rule, one can assume natural alignment when it comes to organizing
the layout of a c1 ass or s t r uc t; however, one should not depend on it.

Assume sizeof(int) =4and sizeof(double) =8.

struct 0 { struct E { struct F {

char d c· _ t int d_i1; int_d_il;
int d 1 • _ t double d- d ,. int d i 2 .
_ t

}; int d- i 2 ., double d_d;

}; };

sizeofCO): 8 sizeof(E): 24 sizeof(F): 16

alignment(D): 4 alignmentCE): 8 alignmentCF): 8

d c ?. ?. d- i1
?.
d- I•

d_d

d- i2

?.

Figure 10-2: User-Defined Types with Holes

Figure 10-2 gives the size, natural alignment, and corresponding object layout of three
user-defined types. Type 0 has a hole in the middle because the second data member is
forced to reside on a word boundary. Type E has two holes: the first hole is caused
because the doubl e, d_d, is forced to start on a double word (8-byte) boundary. The
second hole at the end is to ensure that each element in an array of E objects is also
aligned:
.
given: E a[N], b; II N is compile-time const with value> 0
then: assertCsizeof a == N * sizeof b):
Section 10.1.2 Fundamental Types Used in the Implementation 665

Considering the order in which data members are declared (to reduce object size)
becomes important when there will be many instances of the type active at one time.
We can reorganize the data members of type E in Figure 10-2 to eliminate the holes;
the result is type F, which is 33 percent smaller.

Whenever we attempt to allocate an object in place using the placement syntax for over-
loaded global operator new, we must make sure to do so at a properly aligned location.
We may assume that global new returns addresses that will work for the most restrictive
possible boundary. But we must be careful to avoid code such as the following:

#include <new.h> /1 declare placement syntax

I I ...
char *buf = new char[sizeof(Stack[lOO])];
Stack *p = new(&buf[l]) Stack; II bus error!

An example of ensuring proper alignment within a buffer is given in Figure B-5 of

Appendix B.2.

10.1.2 Fundamental Types Used in the Implementation

We argued in Section 9.2 that it is wise to restrict the selection of fundamental types
used in the interface. The use of unusual fundamental types in the implementation
brings up a separate set of issues.

Guideline
Use short instead of i nt in the implementation as an optimization
only when it is known to be safe to do so.

class win Point {

short d_x;
short d-y;

public:
win_Point(int x, int y);
I / ...
};

Figure 10-3: Using short in the Implementation

666 Implementing an Object Chapter 10

Figure 10-3 illustrates a reasonable use of s h0 r t in the implementation of an object,

assuming that the specification of this class states that the values of both x and y must
be in the range [0, . . . , 1,023] at all times. On a 32-bit architecture where
s i z e 0 f ( s h0 r t) is 2, we stand to fit the entire object in a single 32-bit register. The
potential performance implications in both space and runtime may justify the use of
short in this case. (For a more easily ported approach, see Section 10.1.3.) Justifiable
uses of uns i gned apart from low-level bit-shifting operations 3 are much harder to
come by.

Guideline
Consider not using unsi gned even in the implementation.

class pub_Array { class core_String {

int *d_array_p; char *d_string_p;
unsigned int d_size; unsigned short d_length;

public: public:
pub_Array(unsigned int size); // ...
// ... int length() canst;
}; // ...
};

(a) An Array Class (b) A String Class

Figure 10-4: Inappropriate Use of uns i gned and s ho rt in the Implementation

Figure 10-4 shows two classes in which the use of un signed and s ho rt is misplaced
(assuming a standard 32-bit architecture). In Figure 10-4a, the internal size is made
uns i gned to accommodate an array of up to 2 32 integers, presumably to avoid the pos-
sibility of overflow. This decision has prompted the class author to expose the
un s i 9 ned i n t in the interface as well. Even ignoring the adverse effect on the inter-
face, the reasoning that leads to using un s i 9 ned in this example is twice fallacious.
First, there is no way operator new is going to find space for anywhere near 232 (about
4 billion) contiguous integer-sized objects (for the foreseeable future at least). Sec-
ond, unless a pointer variable is larger than an i nt, the virtual address space limits the

3 ellis, Section 5.8, p. 74.

Section 10.1.3 Using typedef in the Implementation 667

total number of integers: 2 32 + s i zeaf (i nt) ::; 2 30 . In other words, a (signed) i nt,
which can hold positive values of up to 231 - 1, is more than big enough.

Using uns i gned in the implementation to "gain a bit" is an indicat~on

that the fundamental integral type is not large enough to be safe.

In Figure lO-4b, the core_Stri ng class defines its internal size to be a sh"ort because
it does not expect the length of a string to exceed several thousand. The internal vari-
able is then made uns i gned, just in case this value exceeds 32,767. Apart from the
loss in maintainability discussed in Section 9.2.2, in all but pathological cases, if
32,767 isn't known to be large enough, then 65,535 is suspect as well. Making a
s h 0 r t value un s i 9 ned "just in case" is tempting fate-it is usually better to use an
i nt than to risk disaster. The misuse of short in this case is made even more ridicu-
lous because natural alignment will create a hole where the other half of an i n t could
have been placed; using a short here saves nothing. 4

As with any localized, code-tuning effort, the decision to use alternate fundamental
integral types (e.g., short, char) to optimize the storage within an object is best
deferred until after the object is working, has been functionally tested, and perfor-
mance analysis data is available. A suite of thorough regression tests will help to
ensure that we do not optimize the correctness out of our implementation. 5

10.1.3 Using typedef in the Implementation

Typedefs are often helpful for expressing complex function declarations. Typedefs
also have a very useful place in the definitions of certain basic types that assume a
precise number of bits in the representation.

4 For further discussion regarding the inappropriate use of fixed-size arrays in the implementation,
see murray, Section 9.2.2, pp. 210-212.
5 See also murray, Sections 9.9-9.10, pp. 234-235; and cargill, Chapter 7, p. 138.
668 Implementing an Object Chapter 10

Sometimes we know exactly how many bits we need. For example, when we want to
store infonnation persistently (on disk) that is shared across heterogeneous platforms,
we want to make sure that our basic data types hold no more and no less precision
than needed. Figure IO-5a shows a systemwide header file that isolates the definitions
of types with absolute sizes. When porting to a new platform, we need change only
this one file in order to ensure that objects that assume absolute sizes are handled cor-
rectly. For example, Figure IO-5b shows a geom_Poi nt class that requires exactly 32
bits for each coordinate. Typically, an i nt corresponds to the word size of the
machine. Even on a 64-bit architecture we need only 32 bits for compatibility with
other architectures-why waste the space?

II sys_type.h II geom_point.h
#ifndef INCLUDED_SYS_TYPE #ifndef INCLUDED_GEOM_POINT
#define INCLUDED - SYS- TYPE #define INCLUDED_GEOM_POINT

struct sys_Type { #ifndef INCLUDED_SYS_TYPE

typedef signed char Int8; #include "sys_type.h"
typedef short Int16; #endif
typedef int Int32;
typedef unsigned char Uint8;
typedef unsigned Uint16; class geom_Point {
typedef int Uint32; sys_Type: :Int32 d_x;
typedef float Float32; sys_Type::lnt32 d_y;
typedef double Float64;
}; public:
Point (int x, int y);
ifendif I I ...
};

#endif
(a) System-Wide Definitions File (b) Fixed-Size geom_Poi nt Class

Figure 10-5: Using typedef to Specify Fixed Size in the Implementation

In case you thought that only functions are worth testing, consider the test driver for
the sys_type component shown in Figure 10-6. Exercising this driver before any
other ensures that components that depend on fixed-size data types are not "fooling
themselves." We have isolated our configuration assumptions to a single file. Com-
pile-time coupling is not a problem here since the common information derives from
the lower-level compiler and the architecture of the machine (which is fixed), and not
from any higher-level extensible collection of components (which could change).6

6 Section 6.2.9 deals with enumerations and compile-time coupling.

Section 10.2 Function Definitions 669

II sys_type.t.c
#include "test_util.h" II define TEST_ASSERT, etc.
#include "sys_type.h"
maine)
{
TEST_BEGIN
TEST_ASSERTCI == sizeof(Int8));
TEST_ASSERT(2 == sizeof(Int16));
TEST_ASSERT(4 == sizeof(Int32));
TEST_ASSERT(l == sizeof(Uint8));
TEST_ASSERTC2 == sizeof(Uint16));
TEST_ASSERT(4 == sizeof(Uint32));
TEST_ASSERT(4 == sizeofCFloat32));
TEST_ASSERTC8 == sizeofCFloat64));
TEST_END
}

Figure 10-6: Testing a typedef

10.2 Function Definitions

Once we are down to the level of implementing functions, most of our decisions are
localized. The cost of making a poor decision is therefore small, because changing it
typically does not affect a large amount of code. Even so, there are a few general
points to keep in mind when writing function bodies.

10.2.1 Assert Yourself!

Documenting the conditions under which the behavior of a function is undefined is an

important part of developing the interface. Comments in the interface are passive, and
do nothing to warn of a programming error at runtime. As discussed in Section 1.3,
we can use both comments and assert statements in combination to achieve light-
weight maintainable code.

In longer functions, there are sometimes several paths that can lead to the same state-
ment; often this statement assumes internal conditions. Figure 10-7 illustrates a situa-
tion in which either the i f or the wh i 1 e might not be entered. In any case, the stated
condition that follows the if statement must hold true and is backed up by an assert
statement.
670 Implementing an Object Chapter 10

//

if (!q) {
while (p && 0 1= strcmp(name, p-)name()) {
p = p-)next();
}
}

1/ Either q is or p now pOints to the first element

tru~,
II with the specified name if one exists.
assert (q I I !p I I 0 == strcmp(name, p-)name(»);

I I ...

Figure 10-7: Commenting/Asserting an Internal Invariant

These kinds of internal self-checks do more than merely detect errors at runtime. The
practice of explicitly identifying an assumption encourages a crispness of thinking
that typically makes the logical flow of the function easier for others to follow.7

In systems that monitor critical functionality, we might be reluctant to remove the

assert statements even in production code; however, forcing the entire program to
abort when a programming error causes an object to enter an inconsistent state is
clearly not acceptable either. The natural extension of an assert statement would be to
th rowan exception derived from a base class such as sy s_P r og rammi ng Er ro r. In this
case, instead of automatically exiting, fault-tolerant systems could be designed to
cat chand recover from such errors at whatever level had sufficient context to do so.
Failing to catch the error would degenerate to an abort. Notice that by using excep-
tions we have, in effect, "escalated" the responsibility of handling the error to a
higher-level component (see Section 5.2).

10.2.2 Avoid Special Casing

Obtaining code coverage is one common criterion used to measure the effectiveness
of tests. But the more paths there are through a function, the more difficult it can be to
assure ourselves that the function is reliable under all conditions.

7 See also murray, Section 9.2.1, pp. 208-210.

Section 10.2.2 Avoid Special Casing 671

Algorithms that naturally include their boundary conditions are

often simpler, shorter, and easier to understand and to test than
algorithms that treat boundary conditions as a special case.

For example, developers sometimes choose to use a pair of pointers when walking a
list to be modified. This approach requires treating the empty list as a special case (or
always maintaining a dummy first link). Instead of using the pointer to the current
link as a state variable, consider instead maintaining the address of the current link, as
was done for the Pt rBa gMa nip class shown in Figure 5-83.

Figure IO-8a shows an implementation that maintains both a pointer to the current
link and a pointer to' the previous link; the d_p rev Lin k_p pointer will be used to
update the d_next_p field of the previous link when the current link is removed. If the
current link happens to be the first link in the list, d_p rev Lin k_p will be 0, and we
will need to update the root of the list instead; we therefore retain a writable pointer to
the Pt r Ba 9 itself.

The implementation of Figure IO-8a is straightforward but inelegant, complicated by

unnecessary state and algorithmic complexity. Equivalent functionality is accom-
plished with the implementation in Figure IO-8b. Removing the first element in this
implementation is handled in just the same way as removing any other element.

Implementation (b) requires only one state variable, and the complexity of removing a
node is significantly reduced.

A variety of problems can be solved by adding an extra level of

indirection.
 ----r .."'.. .I.U

class PtrBagManip { class PtrBagManip {

PtrBag *d_bag_p; PtrBagLink **d_addrLink_p;
PtrBagLink *d_Link_p;
PtrBagLink *d_PrevLink_p; public:
I I ...
public: void remove();
I I ... I I ...
void remove(); }:
I I ...
}; void PtrBagManip::remove()
{
void PtrBagManip::removeC) PtrBagLink *tmp = *d_addrLink_p;
{ *d_addrLink_p = C*d_addrLink_p)->nextC);
PtrBagLink *tmp = d_Link_p; delete tmp;
d_link_p = d_link_p->next(); }
if (d_prevLink_p) {
d_prevLink_p->nextRefC) - d_link_p;
}
else {
d_bag_p->d_root_p = d_link_p;
}
delete tmp;

(a) Treating the Boundary Condition (b) Treating the Boundary Condition
as a Special Case as Part of the Main Algorithm

Figure 10-8: Avoiding Special-Case Code

The technique of maintaining the address of a pointer instead of the pointer itself is a
terse but powerful idiom for manipulating a variety of list-like structures:

s t r uc t Lin k { Lin k *d_n ex t_p; Lin k( Lin k * next) : d_n e xt_p ( next) {} I I ...

class List { Link *d_head_p; void modify(); II

static int qCconst Link& x); II 1 if some condition on x holds; else 0

void List: :modify() II some function that modifies the list

{
Link **ppl = &d_head_p; II starting at the beginning
while (*ppl && !qC*ppl)) { II while not at end and item not found
ppl = &(*ppl)->d_next_p; II advance the (address of the) pointer
}
assert(!*ppl II q(*ppl)); II ppl points to last or desired Link *
I I ... II insert before, remove, etc. using *ppl
Section 10.2.3 Factor Instead of Duplicate 673

The extra level of indirection allows us to insert an element into an ordered list with-
out having to maintain two pointers or treat the empty list as a special case:

*ppl = new Link(*ppl); II inserting before an item is easy

Removing a specific Link from a list is also facilitated:

if (*ppl) { II if found we can unlink and delete item

Link *item = *ppl;
*ppl = (*ppl )->d_next_p;
delete item;
}

This idiom (or its for-loop equivalent) is used to implement the private functions copy
and end in the List class shown in Figure 6-19b, and is also used extensively to imple-
ment a hash-based symbol table (Figure 10-11) in the following section.

10.2.3 Factor Instead of Duplicate

In Section 5.6 we argued that reuse of small functions could result in physical cou-
pling that is not worth the benefit of a factored implementation. However, within a
single well-designed component, there is little justification for replicating code. Often
construction, destruction, and assignment will share common algorithms. As with the
Lis t class shown in Figure 6-19, it can be useful to define a small set of more primi-
tive functions to factor out commonality from this basic public functionality, as indi-
cated in Figure 10-9.

Default Constructor: init();

Copy Constructor: init(); copy() ;
Assignment Operator: clean(); init(); copy() ;
Destructor: clean();

Figure 10-9: Factoring Common Creator/Assignment Functionality

674 Implementing an Object Chapter 10

It is interesting to note that the assignment operator is not completely primitive; it can be
implemented in terms of the destructor and the copy constructor, which are primitive:

#include "new.h" II declare placement syntax

T& T::operator=(const T& that)
{
if (this != &that) { II check for x = x
T:: ..... T(); II destroy object in place
new(this) T(that); II construct object in place
}
return *this; II return reference to this object
}

This observation has implications for template-based container-class design (see

Section 10.4.2).

Another example of factoring can be found in the implementation of a basic symbol-

table component. A symbol table is a specialization of an associative array that supports
a mapping from a key (most often a character string) to some value (in this case, the
user-defined type my _Va 1ue).

Figure 10-10 shows the header file for a simple implementation of a symbol table.
This implementation uses closed hashing and so is implemented using a dynami-
cally allocated array of my_SymTabL ink pointers (d_tabl e_p) of size derived from
maxEnt ri esHi nt (d_s i ze). There are four basic operations provided: add if not
found, set whether or not found, remove and report if found, and lookup. Each of
these operations can be implemented separately, as shown in Figure 10-11 a. However,
each of these functions basically requires locating the pointer to the symbol (imple-
mented as a my_SymTabL ink). Note that only the remove method requires the address
of the pointer; both add and set can always add a new symbol to the front of the list
for a given hash slot, and lookup never adds a new symbol.

Factoring generally reusable functionality within a component can

reduce code size and improve reliability with only a modest loss in
runtime performance.
Section 10.2.3 Factor Instead of Duplicate 675

II my_symtab.h
#ifndef INCLUDED_MY_SYMTAB
#define INCLUDED_MY_SYMTAB

class my_Value;
class my_SymTabLink;
class my_SymTabIter;

class my_SymTab {
class my_SymTabLink **d_table_p; /1 closed hash table
int d_size; // size of hash table
friend my_SymTablter;

private:
my~SymTab(const my_SymTab&); /1 not implemented
my_SymTab& operator=(const my_SymTab&); II not implemented
public:
I I CREATORS
my_SymTab(int maxSymbolsHint = 0); II see Section 10.3.1
// Optionally specify approx. number of entries (default -500).
-my_SymTab ( ) ;

// MANIPULATORS
my_Value *add(const char* name);
II Adds a symbol to the table only if name is not already present.
II Returns a pointer to the internal value if added, and 0 otherwise.
my_Value& set(const char* name);
II Adds a symbol to the table if not already present. Returns a
II reference to the internal value of a symbol with specified name.
int remove(const char *name);
II Removes a symbol from the table. Returns a if the symbol with
/1 the specified name was found, and non-zero otherwise.

II ACCESSORS
my_Value *lookupCconst char *name) canst:
// Returns a poi nter to an exi sti ng symbol's va 1 ue, or 0 if
II a symbol with the specified name cannot be found.
};

my_SymTabIter { /* ... *1 };

#endif

Figure 10-10: Partial Header for Basic Symbol-Table Abstraction

676 Implementing an Object Chapter 10

II my_symtab.c
# include "my_symtab.h"

char

my_Value *my_SymTab::add(const char *name)

{
int index = hash(name) % d_size:
my_SymTabLink *&slot = d_table_p[index];
my_SymTabLink *p = slot:

while (p && 0 1= strcmp(p->name(), name)) {

p - p->next():
}
if ( ! p) {
slot = new my_SymTabLink(name, slot):
return &slot->value():
}
else {
return o;
}
}

my_Value& my_SymTab::set(const char

{
int index = hash(name) % d_size:
my_SymTabLink *&slot = d_table_p[index];
my_SymTabLink *p = slot;

while (p && 0 != strcmp(p-)name(),

p = p-)next();

( ! p) {
p.= slot = new my_SymTabLink(name,
Section 10.2.3 Factor Instead of Duplicate 677

1/ my_symtab.c
# include "my_symtab.h"

*& :. ". . . . . . . . . . . .
**table,

my_Value *my_SymTab::add(const char *name)

{
my_SymTabLink *& p = locate(d_table_p, d_size, name);
if (p) {
return 0;
}
p - new my_SymTabLink(name, p):
return &p->value();

my_Value& my_SymTab::set(const char *name)

{