API Design for C++

Cover......Page 1
Front matter......Page 2
Copyright......Page 4
Foreword......Page 5
Why You Should Read this Book......Page 6
Who is the Target Audience......Page 7
Conventions......Page 8
Book Web Site......Page 10
Acknowledgments......Page 11
Author Biography......Page 12
Contracts and Contractors......Page 13
APIs in C++......Page 15
Language Compatibility Issues\r......Page 16
More Robust Code......Page 18
Code Reuse......Page 19
Parallel Development......Page 21
When Should you Avoid APIs?......Page 22
Layers of APIs......Page 23
A Real-Life Example......Page 26
File Formats and Network Protocols......Page 28
About this Book......Page 29
Provide a Good Abstraction......Page 32
Model the Key Objects......Page 34
Libraries on Windows......Page 36
Writing Good Tests\r......Page 37
Hide Member Variables......Page 39
Examples and Tutorials......Page 285
Focusing the Testing Effort\r......Page 44
Minimally Complete......Page 45
Don\'t Overpromise......Page 46
Add Virtual Functions Judiciously......Page 47
Convenience APIs......Page 48
Easy to Use......Page 50
Difficult to Misuse......Page 51
Consistent......Page 54
Orthogonal......Page 56
Robust Resource Allocation......Page 58
Platform Independent......Page 62
Loosely Coupled......Page 63
Coupling by Name Only......Page 64
Reducing Class Coupling......Page 65
Intentional Redundancy......Page 67
Manager Classes......Page 69
Callbacks, Observers, and Notifications......Page 70
Callbacks......Page 71
Observers......Page 72
Stable, Documented, and Tested......Page 73
Patterns......Page 75
Pimpl Idiom......Page 77
Constructors and Assignment......Page 185
Copy Semantics......Page 81
Pimpl and Smart Pointers......Page 82
Advantages of Pimpl......Page 83
Disadvantages of Pimpl......Page 84
Opaque Pointers in C......Page 85
Singleton......Page 86
Return Value Const Correctness......Page 87
COM Automation\r......Page 89
Singleton versus Dependency Injection......Page 91
Singleton versus Monostate......Page 92
Singleton versus Session State......Page 94
Factory Methods......Page 95
Abstract Base Classes......Page 96
Simple Factory Example......Page 97
Extensible Factory Example......Page 98
API Wrapping Patterns......Page 101
Supporting Iterators\r......Page 353
Sample Header with Documentation......Page 296
The Façade Pattern......Page 106
Model-View-Controller......Page 109
Implementing the Observer Pattern......Page 111
Push versus Pull Observers......Page 113
A Case for Good Design......Page 115
Accruing Technical Debt......Page 116
Paying Back the Debt......Page 117
Design for the Long Term......Page 119
What Are Functional Requirements?......Page 121
Qualities of a Good Test\r......Page 122
SWIG\r......Page 168
Creating Use Cases......Page 123
Adding Functionality\r......Page 124
Writing Good Use Cases......Page 125
Requirements and Agile Development......Page 127
Shared Library Entry Points......Page 128
Architecture Design......Page 129
Developing an Architecture......Page 131
Architecture Constraints......Page 133
Identifying Major Abstractions......Page 134
Inventing Key Objects......Page 136
Architectural Patterns......Page 139
Communicating the Architecture......Page 140
Object-Oriented Concepts......Page 142
Class Design Options......Page 143
Using Inheritance......Page 144
Liskov Substitution Principle......Page 145
Private Inheritance......Page 147
Composition......Page 148
The Open/Closed Principle......Page 149
The Law of Demeter......Page 150
Class Naming......Page 151
Function Design Options......Page 152
Function Naming......Page 153
Function Parameters......Page 154
Error Handling......Page 156
Styles......Page 161
Flat C APIs......Page 162
Static Libraries......Page 163
Benefits of an ANSI C API......Page 164
Writing an API in ANSI C......Page 165
Calling C Functions from......Page 166
Case Study: FMOD C API......Page 167
Automated API Documentation......Page 283
Case Study: FMOD  API......Page 169
Template-based APIs......Page 170
An Example Template-Based API......Page 171
Inheritance and Enums\r......Page 172
Wrapping a  API with Boost Python\r......Page 345
Data-driven APIs......Page 174
Data-Driven Web Services......Page 175
Class Comments......Page 294
Method Comments......Page 295
Supporting Variant Argument Lists......Page 178
Case Study: FMOD Data-Driven API......Page 180
Namespaces......Page 183
Advantages of Scripting\r......Page 186
Defining Constructors and Assignment......Page 187
The Explicit Keyword......Page 189
Types of Documentation......Page 282
Method Const Correctness......Page 190
Parameter Const Correctness......Page 192
Templates......Page 193
Template Terminology......Page 194
Implicit Instantiation API Design......Page 195
Explicit Instantiation API Design......Page 197
Overloadable Operators......Page 200
Loading Plugins on Linux......Page 408
Adding Operators to a Class......Page 203
The Curiously Recurring Template Pattern\r......Page 205
Conversion Operators......Page 207
Pointer versus Reference Parameters......Page 208
Default Arguments......Page 209
Avoid #define for Constants......Page 210
Avoid Using Friends......Page 212
Exporting Symbols......Page 214
Coding Conventions......Page 217
Performance......Page 219
Reasons to Write Documentation......Page 220
\rPlugin Model Overview......Page 336
Avoid ``Winnebago´´ Headers......Page 222
Forward Declarations......Page 223
Redundant #include Guards......Page 225
An Example Plugin\r......Page 227
The New constexpr Keyword......Page 228
Initialization Lists......Page 229
Extending Via Inheritance\r......Page 380
Don\'t Inline Until You Need To......Page 235
Copy on Write......Page 239
Using Doxygen......Page 243
Random Access......Page 244
Extending Via Templates\r......Page 245
Time-Based Analysis......Page 246
Memory-Based Analysis......Page 248
Multithreading Analysis......Page 249
Version Number Significance......Page 251
Documenting the Interface\'s Contract......Page 253
Creating a Version API......Page 254
Software Branching Strategies......Page 255
Branching Policies......Page 256
APIs and Parallel Branches......Page 257
File Formats and Parallel Products......Page 258
Life Cycle of an API......Page 259
Levels of Compatibility......Page 260
Functional Compatibility......Page 261
Source Compatibility......Page 262
Binary Compatibility......Page 263
Forward Compatibility......Page 265
Finding Dynamic Libraries at Run Time......Page 409
Adding Functionality......Page 266
Changing Functionality......Page 267
Deprecating Functionality......Page 269
API Reviews......Page 271
The Purpose of API Reviews......Page 272
Prerelease API Reviews......Page 273
Precommit API Reviews......Page 275
Documentation......Page 276
Defining Behavior......Page 277
Communicating Behavioral Changes......Page 280
What to Document......Page 281
License Information......Page 286
Documentation Usability......Page 289
The Configuration File......Page 290
Useful Linux Utilities......Page 291
File Comments......Page 293
Reasons to Write Tests\r......Page 299
Types of Api Testing\r......Page 301
Unit Testing\r......Page 303
Integration Testing\r......Page 305
Performance Testing\r......Page 306
What to Test\r......Page 310
Working with QA\r......Page 312
Test-Driven Development\r......Page 313
Stub and Mock Objects\r......Page 316
Testing Private Code\r......Page 319
Constructors\r......Page 321
Contract Programming\r......Page 322
Record and Playback Functionality\r......Page 325
Automated Testing Tools\r......Page 326
Test Harnesses\r......Page 327
Code Coverage\r......Page 330
Bug Tracking\r......Page 333
Continuous Build System\r......Page 334
Script-binding Technologies\r......Page 340
he Plugin Manager\r......Page 376
Python-SIP\r......Page 341
CORBA\r......Page 343
Adding Python Bindings With Boost Python\r......Page 344
Extending the \rPython API......Page 348
Inheritance in \r......Page 351
Cross-Language Polymorphism\r......Page 352
Putting It All Together\r......Page 354
Adding Ruby Bindings With Swig\r......Page 356
Wrapping a  API with SWIG\r......Page 357
Tuning the Ruby API\r......Page 359
Extending the \rRuby API......Page 360
Inheritance in \r......Page 361
Cross-Language Polymorphism\r......Page 363
Putting It All Together\r......Page 364
\rExtending Via Plugins......Page 367
Plugin System Design Issues\r......Page 370
\rImplementing Plugins in......Page 372
The Plugin API\r......Page 373
Plugin Versioning\r......Page 378
Modifying Functionality\r......Page 381
Inheritance and the STL\r......Page 382
The Visitor Pattern\r......Page 384
Prohibiting Subclassing\r......Page 390
Policy-Based Templates\r......Page 392
Static Versus Dynamic Libraries......Page 396
Dynamic Libraries......Page 397
Dynamic Libraries as Plugins......Page 399
Importing and Exporting Functions......Page 400
The DLL Entry Point......Page 401
Creating Libraries on Windows......Page 402
Loading Plugins on Windows......Page 403
Creating Static Libraries on Linux......Page 404
Creating Dynamic Libraries on Linux......Page 405
Creating Dynamic Libraries on Mac OS X......Page 410
Frameworks on Mac OS X......Page 411
Finding Dynamic Libraries at Run Time......Page 412
Bibliography......Page 414
A\r......Page 418
B\r......Page 421
C\r......Page 422
D\r......Page 427
E\r......Page 429
F\r......Page 430
G\r......Page 431
I\r......Page 432
L\r......Page 434
M\r......Page 435
N\r......Page 436
O\r......Page 437
P\r......Page 438
S\r......Page 440
T\r......Page 443
U\r......Page 444
W\r......Page 445
X\r......Page 446