API design for C++

Contracts and Contractors......Page 3
APIs in C++......Page 5
Language Compatibility Issues
......Page 6
More Robust Code......Page 8
Code Reuse......Page 9
Parallel Development......Page 11
When Should you Avoid APIs?......Page 12
Layers of APIs......Page 13
A Real-Life Example......Page 16
File Formats and Network Protocols......Page 18
About this Book......Page 19
Provide a Good Abstraction......Page 22
Model the Key Objects......Page 24
Libraries on Windows......Page 26
Writing Good Tests
......Page 27
Hide Member Variables......Page 29
Examples and Tutorials......Page 275
Focusing the Testing Effort
......Page 34
Minimally Complete......Page 35
Don't Overpromise......Page 36
Add Virtual Functions Judiciously......Page 37
Convenience APIs......Page 38
Easy to Use......Page 40
Difficult to Misuse......Page 41
Consistent......Page 44
Orthogonal......Page 46
Robust Resource Allocation......Page 48
Platform Independent......Page 52
Loosely Coupled......Page 53
Coupling by Name Only......Page 54
Reducing Class Coupling......Page 55
Intentional Redundancy......Page 57
Manager Classes......Page 59
Callbacks, Observers, and Notifications......Page 60
Callbacks......Page 61
Observers......Page 62
Stable, Documented, and Tested......Page 63
Patterns......Page 65
Pimpl Idiom......Page 67
Constructors and Assignment......Page 175
Copy Semantics......Page 71
Pimpl and Smart Pointers......Page 72
Advantages of Pimpl......Page 73
Disadvantages of Pimpl......Page 74
Opaque Pointers in C......Page 75
Singleton......Page 76
Return Value Const Correctness......Page 77
COM Automation
......Page 79
Singleton versus Dependency Injection......Page 81
Singleton versus Monostate......Page 82
Singleton versus Session State......Page 84
Factory Methods......Page 85
Abstract Base Classes......Page 86
Simple Factory Example......Page 87
Extensible Factory Example......Page 88
API Wrapping Patterns......Page 91
Supporting Iterators
......Page 343
Sample Header with Documentation......Page 286
The Façade Pattern......Page 96
Model-View-Controller......Page 99
Implementing the Observer Pattern......Page 101
Push versus Pull Observers......Page 103
A Case for Good Design......Page 105
Accruing Technical Debt......Page 106
Paying Back the Debt......Page 107
Design for the Long Term......Page 109
What Are Functional Requirements?......Page 111
Qualities of a Good Test
......Page 112
SWIG
......Page 158
Creating Use Cases......Page 113
Adding Functionality
......Page 114
Writing Good Use Cases......Page 115
Requirements and Agile Development......Page 117
Shared Library Entry Points......Page 118
Architecture Design......Page 119
Developing an Architecture......Page 121
Architecture Constraints......Page 123
Identifying Major Abstractions......Page 124
Inventing Key Objects......Page 126
Architectural Patterns......Page 129
Communicating the Architecture......Page 130
Object-Oriented Concepts......Page 132
Class Design Options......Page 133
Using Inheritance......Page 134
Liskov Substitution Principle......Page 135
Private Inheritance......Page 137
Composition......Page 138
The Open/Closed Principle......Page 139
The Law of Demeter......Page 140
Class Naming......Page 141
Function Design Options......Page 142
Function Naming......Page 143
Function Parameters......Page 144
Error Handling......Page 146
Styles......Page 151
Flat C APIs......Page 152
Static Libraries......Page 153
Benefits of an ANSI C API......Page 154
Writing an API in ANSI C......Page 155
Calling C Functions from......Page 156
Case Study: FMOD C API......Page 157
Automated API Documentation......Page 273
Case Study: FMOD API......Page 159
Template-based APIs......Page 160
An Example Template-Based API......Page 161
Inheritance and Enums
......Page 162
Wrapping a API with Boost Python
......Page 335
Data-driven APIs......Page 164
Data-Driven Web Services......Page 165
Class Comments......Page 284
Method Comments......Page 285
Supporting Variant Argument Lists......Page 168
Case Study: FMOD Data-Driven API......Page 170
Namespaces......Page 173
Advantages of Scripting
......Page 176
Defining Constructors and Assignment......Page 177
The Explicit Keyword......Page 179
Types of Documentation......Page 272
Method Const Correctness......Page 180
Parameter Const Correctness......Page 182
Templates......Page 183
Template Terminology......Page 184
Implicit Instantiation API Design......Page 185
Explicit Instantiation API Design......Page 187
Overloadable Operators......Page 190
Loading Plugins on Linux......Page 398
Adding Operators to a Class......Page 193
The Curiously Recurring Template Pattern
......Page 195
Conversion Operators......Page 197
Pointer versus Reference Parameters......Page 198
Default Arguments......Page 199
Avoid #define for Constants......Page 200
Avoid Using Friends......Page 202
Exporting Symbols......Page 204
Coding Conventions......Page 207
Performance......Page 209
Reasons to Write Documentation......Page 210

Plugin Model Overview......Page 326
Avoid ``Winnebago´´ Headers......Page 212
Forward Declarations......Page 213
Redundant #include Guards......Page 215
An Example Plugin
......Page 217
The New constexpr Keyword......Page 218
Initialization Lists......Page 219
Extending Via Inheritance
......Page 370
Don't Inline Until You Need To......Page 225
Copy on Write......Page 229
Using Doxygen......Page 233
Random Access......Page 234
Extending Via Templates
......Page 235
Time-Based Analysis......Page 236
Memory-Based Analysis......Page 238
Multithreading Analysis......Page 239
Version Number Significance......Page 241
Documenting the Interface's Contract......Page 243
Creating a Version API......Page 244
Software Branching Strategies......Page 245
Branching Policies......Page 246
APIs and Parallel Branches......Page 247
File Formats and Parallel Products......Page 248
Life Cycle of an API......Page 249
Levels of Compatibility......Page 250
Functional Compatibility......Page 251
Source Compatibility......Page 252
Binary Compatibility......Page 253
Forward Compatibility......Page 255
Finding Dynamic Libraries at Run Time......Page 399
Adding Functionality......Page 256
Changing Functionality......Page 257
Deprecating Functionality......Page 259
API Reviews......Page 261
The Purpose of API Reviews......Page 262
Prerelease API Reviews......Page 263
Precommit API Reviews......Page 265
Documentation......Page 266
Defining Behavior......Page 267
Communicating Behavioral Changes......Page 270
What to Document......Page 271
License Information......Page 276
Documentation Usability......Page 279
The Configuration File......Page 280
Useful Linux Utilities......Page 281
File Comments......Page 283
Reasons to Write Tests
......Page 289
Types of Api Testing
......Page 291
Unit Testing
......Page 293
Integration Testing
......Page 295
Performance Testing
......Page 296
What to Test
......Page 300
Working with QA
......Page 302
Test-Driven Development
......Page 303
Stub and Mock Objects
......Page 306
Testing Private Code
......Page 309
Constructors
......Page 311
Contract Programming
......Page 312
Record and Playback Functionality
......Page 315
Automated Testing Tools
......Page 316
Test Harnesses
......Page 317
Code Coverage
......Page 320
Bug Tracking
......Page 323
Continuous Build System
......Page 324
Script-binding Technologies
......Page 330
he Plugin Manager
......Page 366
Python-SIP
......Page 331
CORBA
......Page 333
Adding Python Bindings With Boost Python
......Page 334
Extending the
Python API......Page 338
Inheritance in
......Page 341
Cross-Language Polymorphism
......Page 342
Putting It All Together
......Page 344
Adding Ruby Bindings With Swig
......Page 346
Wrapping a API with SWIG
......Page 347
Tuning the Ruby API
......Page 349
Extending the
Ruby API......Page 350
Inheritance in
......Page 351
Cross-Language Polymorphism
......Page 353
Putting It All Together
......Page 354

Extending Via Plugins......Page 357
Plugin System Design Issues
......Page 360

Implementing Plugins in......Page 362
The Plugin API
......Page 363
Plugin Versioning
......Page 368
Modifying Functionality
......Page 371
Inheritance and the STL
......Page 372
The Visitor Pattern
......Page 374
Prohibiting Subclassing
......Page 380
Policy-Based Templates
......Page 382
Static Versus Dynamic Libraries......Page 386
Dynamic Libraries......Page 387
Dynamic Libraries as Plugins......Page 389
Importing and Exporting Functions......Page 390
The DLL Entry Point......Page 391
Creating Libraries on Windows......Page 392
Loading Plugins on Windows......Page 393
Creating Static Libraries on Linux......Page 394
Creating Dynamic Libraries on Linux......Page 395
Creating Dynamic Libraries on Mac OS X......Page 400
Frameworks on Mac OS X......Page 401
Finding Dynamic Libraries at Run Time......Page 402
Bibliography......Page 404
A
......Page 408
B
......Page 411
C
......Page 412
D
......Page 417
E
......Page 419
F
......Page 420
G
......Page 421
I
......Page 422
L
......Page 424
M
......Page 425
N
......Page 426
O
......Page 427
P
......Page 428
S
......Page 430
T
......Page 433
U
......Page 434
W
......Page 435
X
......Page 436