Index

Note: Page numbers followed by b indicate boxes, f indicate figures and t indicate tables.

A
Abstract base classes (ABCs)
backward compatibility, 256–257
overview, 86–87
plugin implementation, 366
Abstraction
API design, 118
API problem domain model, 21–23, 22f
architecture design, 124–125
class design, 133
data-driven APIs, 166
iterators, 234
Access control
and #define, 201
and friends, 203–204
and getter/setter routines, 30
proxy patterns, 93
Access levels
encapsulation, language variations, 27
examples, 27f
and logical hiding, 26–27
Active Server Pages (ASP), web development, 8
Actors, use case template elements, 115
Acumen Threadspotter, multithreading analysis, 240
Adaptable systems, architecture classifications, 129
Adapter pattern
definition, 66
overview, 94–96
UML diagram, 94f
Advanced API versions, parallel products, 248
Aggregation, UML class diagram, 23
Agile development, definition, 117–118
AIX, memory-based analysis, 239
Algorithms
API orthogonality, 47
and API usage, 9
behavioral patterns, 65–66
collision detection, 299
functionality compatibility, 252
functionality mismatch, 11
iterators, 233
language APIs, 12
memory-based analysis, 238–239
memory optimization, 221
and namespaces, 174
parallel development example, 9
and STL, 4, 47, 55
use cases, 113, 115
Allocators
mixing, 48, 366, 368
and Pimpl, 74
plugin implementation, 366
AMD CodeAnalyst, for performance analysis, 238
Amiga, header file, 216–217
Android platform, API versions, 373t
Anonymous namespace, and external linkage, 205
ANSI C API
benefits, 154
features, 153–154
FMOD case study, 157–158
function calls from C++, 156–157
keywords, 153–154
type checking, 154b
writing, 155–156
Apache HTTP Server, 279f, 362
Apache License, 278–279
Apache Portable Runtime, 15t
API (Application Programming Interface) basics
in C++, elements, 3–4
code reuse, 7–8
code robustness, 6–7
contractor analogy, 1–2, 3f
definition, 1–4
development life cycle, 249–250
development stages, 106f
encapsulation, language variations, 27b
examples, 11–16
and file formats, 16–17, 16t
layers, 11–14
library example, 2f
and network protocols, 16–17
parallel development, 9–10
purpose, 6–10
real-life example, 14–16, 15t
reasons to avoid, 10–11
and SDKs, 15b
and web development, 8b
API design
API development stages, 106f
architecture design
abstractions, 124–125
communication, 130–131
constraints, 123–124
development, 121–123, 122f
key objects, 126–128
layers examples, 129f
menvshared, 130b
OpenSceneGraph example, 125f
overview, 119–131
patterns, 129–130
basic considerations, 6
class design
composition, 138–139
inheritance, 134–135
Law of Demeter, 140–141
Liskov Substitution Principle, 135–139
naming, 141–142
object-oriented concepts, 132–133
Open/Closed Principle, 139–140
options, 133
overview, 132–142
private inheritance, 137
differences, 4–6
documentation usability, 281
elements, 118–119
explicit instantiation, 187–190
free operator overloading, 192
functional requirements
example, 112
gathering, 111–113
maintaining, 113
function design
error handling, 146–150
naming, 143–144
options, 142–143
overview, 142–150
parameters, 144–146, 145b
implicit instantiation, 185–187
importance, 105–110
for long term, 109–110
overview, 105
plugin systems, 364–365
technical debt
accruing, 106–107
paying back, 107–109
use cases
Agile development, 117–118
creation, 113–118
development, 114
requirements, 117–118
templates, 114–115
writing, 115–116
API design patterns
abstract base classes, overview, 86–87
API consistency, 43, 44
architecture design, 129–130
categories, 65–66
class design, 133
Factory Methods
adapter pattern, 94–96, 94f
extensible example, 88–91
Façade pattern, 96–99, 97f
overview, 85–91
proxy patterns, 91–94, 91f
simple example, 87–88
wrappers, 91–99
Observer pattern
implementation, 101–103
overview, 99–104
push vs. pull, 103–104
UML representation, 101f
overview, 65
Pimpl idiom
copy semantics, 71–72
disadvantages, 74
example, 67f
opaque pointers in C, 75–76
overview, 67–76
smart pointers, 72–73
usage, 67–71
Singleton
vs. dependency injection, 81–82
implementation in C++, 77–79
vs. Monostate, 82–84
overview, 76–85
vs. session state, 84–85
thread safety, 79–81
UML diagram, 76f
techniques, 66
API performance
analysis overview, 235–240
and array references, 235
constant declaration, 217–219
constexpr keyword, 218–219
copy-on-write techniques, 229–233, 229f
and functional compatibility, 252
#include minimization
forward declaration, 213–214
overview, 212–217
redundant guards, 215–217, 215t
“Winnebago” headers, 212–213
initialization lists, 219–221
and inlining, 225–228
input arguments via const reference, 210–212
iterating over elements, 233–235
iterators, 233–234
and member variable hiding, 31
memory-based analysis, 238–239
memory optimization, 221–225, 222f, 222t, 226f
multithreading, 239–240
nonfunctional requirements, 112
overview, 209
random access, 234–235
time-based analysis, 236–238, 237f
API qualities (C++−specific)
coding conventions, 207–208
const correctness
definition, 180–183
method, 180–182
parameter, 182
return value, 182–183
constructors and assignment
compiler-generated functions, 176–177
defining, 177–179
explicit keyword, 179–180
overview, 175–180
#define for constants, 200–202
friends, 202–204
function parameters
default arguments, 199–200
pointer vs. reference parameters, 198–199
namespaces, 173–174
operator overloading
conversion operators, 197–198
free/member functions, 191–193
operator addition to class, 193–195
operator categories, 190–191
overview, 190–198
syntax, 195–196, 195t
overview, 173
symbol export, 204–207
templates
explicit instantiation API design, 187–190
implicit instantiation, 185–187
overview, 183–190
terminology, 184–185
API qualities (general)
coupling
callbacks, 59–62
class coupling reduction, 54–56
manager classes, 58–59, 58f, 59f
by name, 53–54
notifications, 59–62
observers, 59–62
overview, 52–62
redundancy, 56–57
documentation, 62–63
ease-of-use
consistency, 43–45
discoverability, 40
misuse considerations, 40–42
orthogonality, 45–47
overview, 39–52
platform independence, 51–52
resource allocation, 47–50
implementation detail hiding
classes, 33–34
logical hiding, 26–28
member variables, 28–31
methods, 31–33
overview, 25–34
physical hiding, 25–26
key objects model, 23–25, 24f
minimal completeness
convenience APIs, 37–39, 39f
overpromising, 35
overview, 34–39
virtual functions, 36–37
overview, 21
problem domain model
abstraction, 21–23, 22f
overview, 21–25
stability, 62–63
testing, 62–63
API reviews
overview, 261–265
precommit, 265
prerelease, 263–264
purpose, 262–263
Symbian example, 264f
API styles
ANSI C
benefits, 154
features, 153–154
FMOD case study, 157–158
function calls from C++, 156–157
type checking, 154b
writing, 155–156
data-driven APIs
advantages, 166–167
disadvantages, 167–168
FMOD case study, 170–172
overview, 164–172
variant argument lists, 168–170
web services, 165–166
flat C APIs, 151–158
object-oriented C++ APIs
advantages, 158–159
disadvantages, 159
FMOD case study, 159–160
overview, 158–160
overview, 151
template-based APIs
advantages, 163
disadvantages, 164
example, 161–162
vs. macros, 162
overview, 160–164
Apple, See Mac OS X
Application Binary Interface (ABI)
backward compatibility, 257
compatibility, 253
Architecture Description Languages, architecture design communication, 130
Architecture design
abstractions, 124–125
API design, 119
communication, 130–131
constraints, 123–124
development, 121–123, 122f
key objects, 126–128
layers examples, 129f
menvshared, 130b
OpenSceneGraph example, 125f
overview, 119–131
patterns, 129–130
Second Life Viewer, 14, 14f
Arrays
as ANSI C feature, 153
and constructors, 175–176, 177–178, 179
deallocation, 48
and initialization lists, 220
and iterators, 234
Plugin API, 367
random access, 234
reference parameters, 198
references and iterators, 235
variant argument lists, 168
Array subscript
binary operators, 191
syntax, 195t
Assertions
contract programming, 315
data-driven APIs, 167
implicit instantiation design, 186
JUnit, 296
return value tests, 303
testable code writing, 313–314
test harnesses, 319
unit testing, 295
Assignment operator
class design, 133
compiler-generated functions, 177
and copy on write, 233
copy semantics, 71–72
C++−specific APIs
compiler-generated functions, 176–177
defining, 177–179
overview, 175–180
initialization lists, 220
overloading, 190
and Pimpl, 72–73
and singletons, 77
Association, UML class diagram, 23
at() method, and random access, 234
AutoDuck, documentation generation, 275
Automated documentation, creation, 274–276
Automated GUI testing, overview, 294
Automated Teller Machine (ATM)
functional requirements, 112–113
use case example, 116
user stories, 117–118
Automated testing
API design, 6
bug tracking, 325–326
code coverage, 322–325, 324f
continuous build systems, 326, 327f
test harnesses, 319–322
tool categories, 318–326

B

Backward compatibility
API design, 4
API reviews
overview, 261–265
precommit, 265
prerelease, 263–264
purpose, 262–263
binary compatibility, 253–255
default arguments, 199
definition and types, 251
functional compatibility, 251–252
maintenance
deprecating functionality, 259–261
functionality addition, 256–257
functionality changing, 257–259
overview, 256–261
removing functionality, 261
patch version, 242
source compatibility, 252–253
testing, 292
and visitor pattern, 383–384
Basic API versions, parallel products, 248
Basic block coverage, testing tools, 323
Basic course
ATM use case example, 116
use case template elements, 115
Behavioral design patterns, examples, 65–66
Behaviors
defining with documentation, 268–269
documentation, 271–272
key objects, 126
mock objects, 310
Best practices
API design, 149
API qualities, 63
C function calls, 157
coding conventions, 208
#define, 201–202
error reporting, 149–150
function parameters, 198
operators, 192
plugin implementation, 366
template-based APIs, 161
“The Big Three” rule, 176
Binary compatibility
ANSI C API, 154
maintenance, 259
in object-oriented C++ APIs, 159
overview, 253–255
Pimpl idiom, 74
Binary instrumentation, time-based performance analysis, 236
Binary operators
overloading, 191
symmetry, 192
Bit fields, memory optimization, 222, 225
Black box testing
definition, 293
integration testing as, 297
and STE, 305
Booleans
and API ease-of-use, 41
code coverage, 323
and LLSD, 168
Ruby API tuning, 352
unit testing, 295–296
Boost library
and copy on write, 229–231
and coupling, 61
error handling, 148
for extending, 385
implicit instantiation API design, 187
template-based APIs, 161
Boost Python
API extension, 341–343
code example, 347–349
construction, 338
constructors, 341
cross-language polymorphism, 345–346
features, 334
inheritance, 344–345
iterator support, 346–347
overview, 337–349, 337f
scripting and language barrier, 333
wrappings, 338–341
Boost Test, overview, 320
Boundary conditions, definition, 302
Branching strategies, See Software branching strategies
Breadcrumbs, documentation usability, 280
BSD License, 278–279
Buffer overruns, definition, 303
Bug tracking
definition, 318
testing tools, 325–326
Bugzilla, 325
Bullseye Coverage, testing tools, 323
Business logic, data-driven APIs, 166
Business requirements, definition, 111

C

Caching
code robustness, 7
and getter/setter routines, 29
and performance, 235
Callbacks
and architecture design, 130
and coupling, 59–62
and Factory methods, 88–89
and friendship, 202
and Plugin API, 367
and plugins, 366, 369
Callgrind, for performance analysis, 238
Calling convention, adapter pattern, 96
Case studies
FMOD C API, 157–158
FMOD C++ API, 159–160
FMOD data-driven API, 170–172
Cast operators, variant argument lists, 168
CcDoc, documentation generation, 275
Chaining
function calls, 140
operators, 175
Change control process, API design, 5
Change request process, API design, 5
Circular dependency, architecture design, 129f
C language basics
See also ANSI C API
features, 153–154
opaque pointers, 75–76
plugin system design, 364
C++ language basics
API elements, 3–4
plugin implementation, 366
Class comments, Doxygen, 285–286
Class concept
coding conventions, 208
definition, 132
documentation basics, 272
in object-oriented C++ APIs, 158
operator addition, 193–195
Class design
composition, 138–139
inheritance, 134–135
Law of Demeter, 140–141
Liskov Substitution Principle, 135–139
naming, 141–142
object-oriented concepts, 132–133
Open/Closed Principle, 139–140
options, 133
overview, 132–142
private inheritance, 137
Class diagrams
design notations, 127
implementation hiding, 33–34
UML, 23b, 128f
Class hierarchy
API design, 119
example, 120f
Class invariant, contract programming, 270
Client applications, and API performance, 226
Client/server protocol, and APIs, 16
C linkage
Plugin API, 367, 370
plugin implementation, 366
Cocoa (Apple)
event ordering, 60
and MVC, 100
“Winnebago” headers, 212
Code bloat, and API performance, 226
Code coverage
definition, 318
testing tools, 322–325
Code duplication, and API code robustness, 7
Code examples
C++ usage
compiler-generated functions, 176–177
const method, 180–181
constructors and assignment, 175–176, 177–178
conversion operators, 197–198
default arguments, 199
#define, 200–201
explicit instantiation, 188
friendship, 203
implicit instantiation, 186
namespaces, 174
operators, 191, 193–194
return value const, 182–183
symbol exporting, 204, 206–207
template example, 184
design
composition, 138
error handling, 147–148
function parameters, 144–145
Law of Demeter, 140
Liskov substitution principle, 135–136
private inheritance, 137
renderer factory, 139
design patterns
ABCs, 86
adapter pattern, 94–95, 96
copy semantics, 72
extensible factory methods, 89
façade pattern, 97–98
observer pattern, 101–102
opaque pointers, 75
Pimpl and smart pointers, 72–73
Pimpl use, 68–71
proxy pattern, 91–92
simple factory methods, 87
singleton vs. dependency injection, 81–82
singleton vs. monostate, 83
singletons, 77–78
thread-safe singletons, 79
documentation
behavioral changes, 271
defining behavior, 268
documentation usability, 280, 281
interface contract, 270
Doxygen documentation
API comments, 283–284
class comments, 285–286
commands, 282–283
comment style, 282
configuration file, 281–282
enum comments, 287
file comments, 284–285
header, 287–289
method comments, 286
extensibility
adding functionality, 374
CRTP, 387
enums, 377–378
modifying functionality, 375–376
Plugin API, 367, 369–370
Plugin Manager, 370–371
Plugin versioning, 373
policy-based templates, 386
STL, 376
subclassing, 384–385
visitor pattern, 379–380
general
“Hello World”, 4
“Hello World” with Qt, 13
parallel development, 9
STL for vector iteration, 12
TIFF dimensions with libtiff, 12
triangle render with OpenGL, 13
performance
constant declarations, 217
constexpr, 219
const references, 211–212
copy on write, 230
forward declarations, 213
initialization lists, 219
inlining, 227
iterators, 233
memory optimization, 223
random access, 234
redundant #include guards, 216–217
quality basics
callbacks, 61
class coupling reduction, 54–55
class hiding, 33–34
consistency, 44
convenience APIs, 38
coupling by name, 53–54
difficult to misuse APIs, 40
intentional redundancy, 56
member variable hiding, 28–29, 30–31
method hiding, 31–32
notifications, 62
orthogonality, 45–46
physical hiding, 25
platform independence, 51
robust resource allocation, 48–49
scripting
COM automation, 335–336
CORBA, 336–337
Python-SIP, 335
SWIG, 334
scripting with Boost Python
bindings, 347–349
constructors, 341
cross-language polymorphism, 345
inheritance, 344
iterators, 346–347
Python extension, 342
sample program, 347–349
wrappings, 338–341
scripting via Ruby with SWIG, 357–359
constructors, 353
cross-language polymorphism, 356–357
extension, 353–354
inheritance, 354–355
sample program, 357–359
tuning, 352
wrappings, 350
styles
ANSI C API, 155
C function calls, 157
data-driven APIs, 164, 166
FMOD C API, 157–158
FMOD C++ API, 159–160
FMOD data-driven API, 170–172
template-based API, 161, 163
templates vs. macros, 162
variant argument lists, 169–170
testing
assertions, 313
Boost Test, 320
code coverage, 322–323
contract programming, 315
CppUnit, 319
Google Test, 321
mock objects, 309–310
playback functionality, 317
self-testing, 311–312
stub objects, 308–309
testable code, 305–306
TUT, 321
unit testing, 295–296
versioning
binary compatibility, 253
forward compatibility, 255
source compatibility, 252
version API creation, 244
versioning and backward compatibility
adding functionality, 256–257
changing functionality, 257–258
deprecating functionality, 260
CodeProphet Profiler, for performance analysis, 238
Code reuse
and API usage, 7–8
and scripting, 330
Code robustness, and API usage, 6–7
Coding conventions, C++−specific APIs, 207–208
Coding standards, as test quality, 302
Cohesion, definition, 52
Commenting
coding conventions, 208
defining behavior, 268–269
Doxygen
API comments, 283–284
class comments, 285–286
enum, 287
file comments, 284–285
method comments, 286
style, 282–283
Common Lisp, and SWIG, 334
Common Object Request Broker Architecture (CORBA), features, 336–337
Communication
architecture design, 130–131
behavioral changes, 271–272
Community catalyst, plugin-based extensibility, 362
Compatibility levels
basic considerations, 250–256
binary compatibility, 253–255
forward compatibility, 255–256
source compatibility, 252–253
Compile errors
and copy semantics, 71
and ease-of-use, 41
and parameter lists, 146
and subclassing, 384–385
and type checking, 154
Compiler-generated functions, C++−specific APIs, 176–177
Compile-time speed
definition, 209
and explicit instantiation, 184
and redundant #include guards, 215t
template-based APIs, 164
Completion, API life cycle, 249f, 250
Compliance testing, 292, 293
Component Object Model (COM), features, 335–336
Composition
and adapters, 95
class design, 133, 138–139
coding conventions, 208
and inheritance, 134
vs. inheritance, 138
and intimacy, 53
and LSP, 137
and OCP, 139
OOP definition, 132
and STL, 377
UML class diagram, 23
Concurrency
and API usage, 14
architecture constraints, 123
design patterns, 66
multithreading analysis, 239–240
nonfunctional requirements, 112
singleton thread safety, 80
testing, 294
Condition coverage
code coverage, 324
testing tools, 323
Condition testing, definition, 302
Configuration file
Boost Python, 338
Doxygen, 281–282, 283
factory method example, 88
integration testing, 297–298
member variable hiding, 29
and parallel development, 9
Consistency
adapter pattern, 95
API design, 262
API ease-of-use, 43–45
automated API documentation, 274
and backward compatibility, 261
coding conventions, 207
documentation “look and feel”, 280
random access functionality, 234–235
Constants (general)
declaration, 217–219
and #define, 200–202
documentation basics, 272
naming conventions, 208
Const correctness
coding conventions, 208
definition, 180–183
method, 180–182
parameter, 182
return value, 182–183
constexpr keyword, 218–219
Const references
and assignment operators, 175
containers, 332
forward declarations, 214
function design, 142–143
function parameters, 199
input argument passing, 210–212
return value const correctness, 182–183
Constructors
ANSI C API, 155–156
behavior documentation, 268
Boost Python bindings, 339, 341
class design, 133
coding conventions, 208
compiler-generated functions, 176–177
copy semantics, 71–72
default arguments, 200
defining, 177–179
error handling, 148–149
explicit keyword, 179–180
factory methods, 85, 88
function design, 142
function parameters, 145–146
implementation method hiding, 32
and inheritance, 376
and initialization lists, 219–221
input argument passes, 211
operator symmetry, 192
overview, 175–180
Pimpl, 68, 72, 74
resource allocation, 50
Ruby with SWIG, 353
singleton vs. dependency injection, 82
singleton vs. monostate, 84
and singletons, 77
static initialization, 81
stub objects, 308
and subclassing, 384–385
virtual functions, 37
Container classes
API comments, 283
array references, 235
and consistency, 43–44
coupling, 55
dependency, 82
documentation, 270–271
forward compatibility, 256
and friends, 204
function naming, 143
iterators, 233, 346–347
language compatibility, 332
layers of APIs, 12
namespaces, 174
and orthogonality, 47
performance testing, 299
random access, 234
robust code, 7
STL, 4, 161, 332, 339, 366, 376, 385
variant argument lists, 168
Continuous build systems
definition, 319
example, 327f
testing tools, 326
Contractor analogy, API definition, 1–2, 3f
Contract programming
overview, 269–271
testable code writing, 314–317
Convenience APIs
and core APIs, 39f
Façade pattern, 98
usage, 37–39
Conversion operators
class design, 133
and explicit keyword, 180
overloading, 197–198
Copy constructor
argument passing, 211
class design, 133
compiler-generated, 71–72, 176–177
copy semantics, 71–72
C++−specific APIs, 175
defining, 133, 177–178
error handling, 149
explicit declaration, 179–180
input argument passes, 211
and Pimpl, 72–73, 74
and singletons, 77
Copyleft license, definition, 278
Copy-on-write techniques
and API performance, 229–233
example, 229f
Copy semantics, Pimpl idiom, 71–72, 73
Core API
plugin API communication, 367
Plugin Manager, 364f, 372
plugin versioning, 372–373
Counter monitoring, time-based performance analysis, 236
Coupling
API qualities
callbacks, 59–62
class coupling reduction, 54–56
manager classes, 58–59, 58f, 59f
by name, 53–54
notifications, 59–62
observers, 59–62
overview, 52–62
redundancy, 56–57
definition, 52
and operator overloading, 192
Pimpl idiom, 74
Coverity, for performance analysis, 239
CppDoc, documentation generation, 275
CppUnit
and JUnit, 296
overview, 319
CPython, 337
Creational design patterns, examples, 65–66
Cross-language polymorphism
Boost Python bindings, 345–346
Ruby bindings with SWIG, 356–357
in script binding, 333
Cross-Platform Component Object Model (XPCOM), COM automation, 336
C# language
and API qualities, 21
Doxygen, 281
formal design notations, 127
robust resource allocation, 47–48
and SWIG, 334
CUnit, 296
Curiously Recurring Template Pattern (CRTP), for extending, 387–389
Cyclic dependency, architecture design, 129f

D

Data-driven APIs
advantages, 166–167
definition, 151
disadvantages, 167–168
FMOD case study, 170–172
overview, 164–172
variant argument lists, 168–170
web services, 165–166
Data formats, documentation usability, 281
Data types
adapter pattern, 95
API orthogonality, 47
Dates, as version numbers, 243
Debt, See Technical debt
Debugging
and API performance, 226
and getter/setter routines, 29
Debug modes, proxy patterns, 93
Decision coverage, testing tools, 323
Declarations
ANSI C API, 155
automated API documentation, 274
coding conventions, 208
constants, 217–219
constexpr keyword, 218–219
constructors, 353
constructors and assignment, 175, 177–178
copy on write, 229–231
copy semantics, 71
coupling by name, 53–54
definition, 25
deprecation, 260
and explicit keyword, 179
and external linkage, 205
implementation detail hiding, 25–26
#include minimization, 213–214
and inheritance, 132
inlining, 227–228
method hiding, 32–33
operator samples, 195t
physical hiding, 25
private inheritance, 138–139
Separation Model, 187
singleton vs. monostate, 83
template-based APIs, 161, 163
templates vs. macros, 162
template terminology, 184
test harnesses, 319
“Winnebago” headers, 212–213
Default arguments
ANSI C features, 153
binary compatibility, 254
Boost Python, 334
C++−specific APIs, 199–200
Default constructor
Boost Python, 341
compiler-generated functions, 176–177
copy semantics, 71–72
C++−specific APIs, 175
definition, 175
factory methods, 85
initialization lists, 220
Ruby with SWIG, 353
singleton implementations, 77
#define (general)
coding conventions, 208
and constants, 200–202
version API creation, 244
Definition
API and parallel branches, 248
assertions, 313–314
and composition, 138–139
copy on write, 229–231
defining behavior, 268
definition, 25
explicit instantiation design, 187–188
forward declarations, 54, 213
implicit instantiation design, 184, 185–186
and namespaces, 173
orthogonal design, 47
physical hiding, 25–26
Pimpl, 67
and SWIG, 349
template-based API, 161, 164
templates, 184
“Winnebago” headers, 212
Dependency injection, vs. Singleton, 81–82
and stub objects, 310
Dependency problems
architecture patterns, 129–130, 129f
#include minimization
forward declarations, 213–214
overview, 212–217
“Winnebago” headers, 212–213
Deprecation
API life cycle, 250
backward compatibility, 259–261
overview documentation, 276
release notes, 277
Description
ATM use case example, 116
use case template elements, 114
Design by contract, See Contract programming
Destructors
ABCs, 86–87
ANSI C API, 155–156
class design, 133
coding conventions, 208
compiler-generated functions, 176–177
copy semantics, 71–72
C++−specific APIs, 175
and inheritance, 134, 344, 374–375, 376
input argument passes, 211
mock object, 310
object-oriented API disadvantages, 159
Pimpl, 68, 72, 74–75
and resource allocation, 49
singleton vs. monostate, 84
singletons, 77
stub objects, 308–309
and subclassing, 384–385
virtual functions, 37
Diagrams, as documentation type, 280
DirectX, 3D graphics APIs, 12
Discoverability
as API quality, 40
automated API documentation, 274
function naming, 143
function parameters, 144
Distributed systems, architecture classifications, 129
Doc++, documentation generation, 275
Doc-O-Matic, documentation generation, 275
Documentation
Apache HTTP Server example, 279f
API avoidance, 11
API design, 6
API problem domain model, 21–22
API qualities, 62–63
API reviews, 263–264
via assertions, 313
automated documentation, 274–276
behavior changes, 271–272
C++ API elements, 3
for defining behavior, 268–269
definition, 267
design by contract, 269–271
Doxygen
API comments, 283–284
class comments, 285–286
commands, 282–283
comment style, 282–283
configuration file, 281–282
file comments, 284–285
method comments, 286
overview, 281–289
sample header, 287–289
elements to document, 272–273
examples/tutorials, 276–277
good qualities, 273
license information, 277–280
overview documentation, 276
overview of types, 273–280
purpose, 267–273
Qt Reference Documentation, 275f
release notes, 277
tools for creation, 275–276
usability, 280–281
Documentation lead, prerelease API reviews, 263
Domain analysis
See also Problem domain
Evans, 127
Neighbors, 126
Shlaer–Mellor, 126
Double Check Locking Pattern (DCLP), Singleton thread safety, 80
Doxygen
API comments, 283–284
class comments, 285–286
commands, 282–283
comment style, 282–283
configuration file, 281–282
definition, 267
documentation generation, 275
enum comments, 287
file comments, 284–285
HTML output example, 285f
interface documentation, 159
method comments, 286
prerelease API reviews, 263–264
private code testing, 312
sample header with documentation, 287–289
usage, 281–289
DRD, multithreading analysis, 240
“Dry run” modes, proxy patterns, 93
DTrace, for performance analysis, 238
Dynamic libraries
binary compatibility, 253
Boost Python, 334, 337, 337f, 340
C++ API elements, 3
extensibility, 361
plugin extensibility, 361, 362f
Plugin Manager, 370
plugin system design, 364, 365
Ruby API tuning, 352–353
Ruby with SWIG, 350f
and startup time, 210
vs. static, 365
symbol exporting, 206

E

Ease-of-use
consistency, 43–45
discoverability, 40
misuse considerations, 40–42
orthogonality, 45–47
overview, 39–52
platform independence, 51–52
resource allocation, 47–50
Eiffel language, contract programming, 316
Electric Cloud, definition, 326
Embedding
forward declarations, 214
private code testing, 312
script binding, 329–330
Encapsulation
and class coupling, 54–55
definition, 28, 132
and friends, 133, 204
implementation member hiding, 32
language variations, 27b
logical hiding, 26–28
and manager classes, 59
member variable hiding, 28–29
in object-oriented C++ APIs, 159
and Pimpl, 71
return value const correctness, 183
and symbol exporting, 204–205
enum keyword (general)
and binary compatibility, 254
vs. booleans, 41
and code bloat, 218
coding conventions, 208
vs. #define, 202
definition, 153
documentation basics, 272
Doxygen comments, 287
and inheritance, 377–378
and namespaces, 174
and type safety, 202
Environmental factors, architecture design, 123
Equivalence classes, definition, 302
Error codes
contract programming, 316
internalization support, 318
template-based APIs, 164
Error handling
API consistency, 43
function design, 146–150
record/playback functionality, 317
Event domains, key objects, 126
Event ordering, definition, 60
Evolution strategy, definition, 108
Examples, as documentation type, 276–277
Exceptions
API consistency, 43
and binary compatibility, 255
Boost Python, 334
coding conventions, 208
documentation basics, 273
error handling, 147
language barriers, 333
plugin implementation, 366
STL, 377
test harnesses, 319, 320
Expert users, scripting advantages, 331
Explicit instantiation
API design, 187–190
and backward compatibility, 258
definition, 184
inlining, 227
template-based APIs, 164
templates, 184
explicit keyword
class design, 133
conversion operators, 198
C++−specific APIs, 179–180
function design, 142
Explicit specialization, definition, 185
Expressiveness, scripting advantages, 331
Extensibility
via inheritance
and enums, 377–378
example, 375f
functionality addition, 374–375
functionality modification, 375–376
overview, 374–385
and STL, 376–377
subclassing, 384–385
visitor pattern, 378–384, 381f
overview, 361
via plugins
benefits, 362–363
Netscape Plugin API, 363b
overview, 361–374
Plugin API, 367–370
plugin implementation, 366
Plugin Manager, 370–372
system design issues, 364–365
versioning, 372–374
Ruby API, 353–354
script binding, 329–330
scripting advantages, 331
via templates
CRTP, 387–389
overview, 385–389
policy-based templates, 386–387
Extensible Markup Language, See XML (Extensible Markup Language)
Extensions
ATM use case example, 116
C++ plugins, 366
Firefox web browser, 331, 365
Netscape Plugin API, 363
OpenGL API, 245
use case template elements, 115
External linkage
private code testing, 313
symbol export, 204
External metadata, plugin system design, 365

F

Façade pattern
definition, 66
overview, 96–99
UML diagram, 97f
Facebook, and C++ APIs, 8
Factory Methods
adapter pattern, 94–96, 94f
definition, 66
extensible example, 88–91
Façade pattern, 96–99
overview, 85–91
proxy patterns, 91–94, 91f
simple example, 87–88
wrappers, 91–99
Failure reproducibility, as test quality, 302
Fake Object, definition, 308
Fast Fourier Transform (FFT), API avoidance, 11
Feature tags, version API creation, 245
FIFA 10, version numbers, 243
File comments, Doxygen, 284–285
File formats
and APIs, 16–17
software branching strategies, 248–249
Fixture setup, unit testing, 296
Flat C APIs
backward compatibility, 258
binary compatibility, 255
definition, 151
examples, 151–158
Flexibility
and coupling, 53
nonfunctional requirements, 112
FMOD API
C case study, 157–158
C++ case study, 159–160
data-driven APIs, 166, 170–172
definition, 151
Formatting, coding conventions, 208
Fortran, Doxygen, 281
Forward compatibility
overview, 255–256
patch version, 242
Forward declaration
coding conventions, 208
coupling by name, 53–54
#include minimization, 213–214
private inheritance, 138–139
Foundation Class library (Microsoft), and MVC, 100
Fragility, technical debt, 107
Framework
application/GUI, 15b, 376
Mac OS X, 406
Free, Libre, Open Source Software (FLOSS)
definition, 277
license types, 278–279
FreeBSD, 238
Free functions
function design, 142
naming, 143–144
overloading, 191–193
plugin implementation, 366
Free and Open Software (FOSS), definition, 277
Free operators, vs. member operators, 191–193
Free Software Foundation (FSF), FLOSS licenses, 278
Frequently Asked Questions (FAQs), as documentation type, 277
Friend function
function design, 142
private code testing, 311
Friends
avoiding, 202–204
and binary compatibility, 254
class design, 133
C++−specific APIs, 202–204
free operators, 192–193
and Law of Demeter, 140
and operator additions, 194
private code testing, 311
Friendship, and encapsulation, 27
Functional compatibility
addition, 256–257
changing, 257–259
deprecation, 259–261
overview, 251–252
removal, 261
Functionality extension, via inheritance, 374–376
Functionality mismatch, API avoidance, 11
Functional requirements
See also Use cases
definition, 111–112
example, 112
gathering, 111–113
maintaining, 113
Function calls
callbacks, 61
C functions from C++, 156–157
constant declarations, 218
contract programming, 314
C++ Plugins, 366
data-driven APIs, 164
error handling, 147
flat C APIs, 151–152
function coverage, 322
function design, 142
key objects, 126
Law of Demeter, 140
mock objects, 309–310
Observer pattern, 103
operators and syntax, 195t
order independence, 146
playback functionality, 317
Proxy pattern, 93
Ruby with SWIG, 356–357
time-based analysis, 236
unary operators, 190
virtual functions, 36
Function coverage
code coverage, 324
testing tools, 322
Function design
error handling, 146–150
naming, 143–144
options, 142–143
overview, 142–150
parameters, 144–146, 145b
Function documentation, 272
Function parameters
default arguments, 199–200
function design, 144–146, 145b
pointer vs. reference parameters, 198–199
Future proofing, plugin-based extensibility, 362

G

Gcov
example, 324f
testing tools, 324
Generalization
class hierarchy, 119
factory methods, 85
UML class diagram, 23
Generic Plugin Manager, plugin system design, 365
GenHelp, documentation generation, 275
Getter/setter methods
Boost Python, 339
and class coupling, 54–55
class hiding, 34
constant declarations, 218
function parameters, 146
inlining, 227
language compatibility, 332
member variable hiding, 28–29
Ruby API tuning, 352
singleton vs. dependency injection, 82
and testing, 303
GL, See OpenGL (GL)
Global constants, declaration, 218
Global state, Singleton design pattern, 76–77
Gnome, bug tracking, 325
GNOME GLib, as flat API, 152
GNU C++ compiler
performance analysis, 238
symbol export, 206
GNU General Public License (GPL)
API and licence restrictions, 10
Doxygen, 281
FLOSS license, 278–279
GNU Image Manipulation Program (GIMP), plugin-based extensibility, 362–364
GNU LGPL, FLOSS license, 278–279
Goal
ATM use case example, 116
use case template elements, 114
Google Mock, testable code writing, 309–310
Google Test, overview, 321
GProf, for performance analysis, 238
GPS devices, API platform independence, 51
Graphics User Interface (GUI)
API definition, 13
vs. API design, 4–5
Gray box testing, definition, 293
GTK+
C++−specific APIs, 173
GUI APIs, 13

H

Hardcoded assumptions, and API code robustness, 7
HeaderDoc, documentation generation, 275
Header files
assertions, 313
automated documentation, 274
Boost, 228, 338, 347–349
callbacks, 61
C++ API elements, 3
C function calls, 157
class comments, 285–286
class hiding, 34
coding conventions, 208
comments, 284–285
data-driven APIs, 166–168
documentation, 267, 269, 287–289
factory methods, 88
forward declarations, 213
and global scope, 218
implement hiding, 220, 227
#include guards, 216
Inclusion Model, 187
inlining, 225–226, 229–231
JFIF format, 16t
method hiding, 32
namespaces, 174
OOP disadvantages, 159
opaque C pointers, 75
physical hiding, 26
and Pimpl idiom, 66, 67, 73
platform independence, 51
Plugin API, 367
SDK basics, 15
SWIG wrapping, 350, 357–359
template-based APIs, 164
template instantiation, 184, 185–186, 188
and testing, 318
versioning, 253
“Winnebago” headers, 212–213
Helgrind, multithreading analysis, 240
“Hello World” program
API design, 4
GUI APIs, 13
scripting example, 330
Help Generator, documentation generation, 275
Hiding implementation details, See Information hiding
HP-UX, memory-based analysis, 239
Hypertext Mark-up Language (HTML)
documentation output, 275–276
Doxygen output example, 285f
Doxygen sample header, 287–289
gcov/lcov code example, 324f
Hypertext Transfer Protocol (HTTP), data-driven APIs, 165–166

I

IBM Rational Purify, for performance analysis, 239
IDLscript, and CORBA, 336
Image APIs, definition, 12
Image Libraries, as flat API, 152
Immobility, technical debt, 107
Implicit instantiation
API design, 185–187
definition, 184
templates, 184
import keyword, Boost Python bindings, 340–341
Inclusion Model, templates, 187
Independence
API orthogonality, 47
platform, See Platform independence
Index page, documentation usability, 280
Information hiding
ANSI C API, 155
API wrapping, 91
classes, 33–34
constants, 217, 218
copy on write, 229–231
and #define for constants, 201
encapsulation, 132
explicit instantiation, 184, 187, 189
factory methods, 88
flat C APIs, 152
function parameters, 146
implicit instantiation, 185–186
initialization lists, 220
inline statements, 228
legacy code, 98, 108
logical hiding, 26–28
member variables, 28–31
methods, 31–33
object-oriented API disadvantages, 159
overview, 25–34
physical hiding, 25–26
Pimpl idiom, 66, 67, 73
and platform independence, 51–52
private code testing, 311
robust code, 6
scope-free functions, 205
singleton vs. monostate, 83
symbols, 206
template-based APIs, 164
virtual functions, 37
virtual methods, 135
Information overload, performance testing, 300
Inheritance
Boost Python bindings, 344–345
class design, 133, 134–135
vs. composition, 138
contract programming, 271
data-driven APIs, 169
definition, 132
for extending
and enums, 377–378
functionality addition, 374–375
functionality modification, 375–376
overview, 374–385
and STL, 376–377
subclassing, 384–385
visitor pattern, 378–384, 381f
and minimal completeness, 36
in object-oriented C++ APIs, 158, 159
private, 137
with SWIG, 354–356
In-house instrumentation, time-based performance analysis, 236
Initialization
class design, 133
factory methods, 85, 91
and Plugin Manager, 370
reference parameters, 198
singleton implementation, 78
singleton vs. monostate, 83
singleton thread safety, 79
static, 81
Initialization function
Plugin API, 367
Plugin example, 369
Plugin Manager, 370
plugin system design, 365
Initialization lists
API performance, 219–221
coding conventions, 208
and performance, 219–221
Pimpl, 72
Inline methods
and API performance, 225–228
and copy on write, 229–231
and private headers, 187
Input argument pass, by const reference, 210–212
Instantiation
API design, 185–190
and backward compatibility, 258
definition, 184
and inlining, 227
proxy pattern, 93
singleton thread safety, 80–81
templates, 184
Integration testing, overview, 297–298
Intel Code-Coverage Tool, testing tools, 324
Intel Parallel Studio, multithreading analysis, 240
Intel Thread Checker, multithreading analysis, 239
Intel Thread Profiler, multithreading analysis, 240
Intel VTune, for performance analysis, 237
Intentional debt, definition, 106–107
Interaction domains, key objects, 126
Interactive systems, architecture classifications, 129
Interface description language (IDL), COM automation, 335–336
Internalization, testable code writing, 318
Internal metadata, plugin system design, 365
Intimacy, and coupling, 53
Invariant relationships, and getter/setter routines, 30
INVEST, definition, 118
Iostream library, STL extension, 377
Iron Python, 337
Iterators
and API performance, 233–234
and array references, 235
Boost Python bindings, 346–347
language compatibility, 332
and random access, 234–235

J

Java
ABCs, 86
and API qualities, 21
Doxygen, 281
encapsulation, 27
formal design notations, 127
inheritance, 135
OOP origins, 158
package-private, 27
robust resource allocation, 47–48
subclassing, 384
and SWIG, 334
JavaScript
and CORBA, 336
extensibility, 331
plugin security, 365
JavaScript Object Notation (JSON), 165–166
Java Swing, MVC, 100
JPEG File Interchange Format (JFIF)
and APIs, 16
header specification, 16t
image APIs, 12
JScript, and COM automation, 335
JUnit testing, overview, 296b
Jython, 337

K

KDOC, documentation generation, 275
KDU JPEG-2000 decoder library, Façade pattern, 99
Key objects
architecture design, 122, 122f
invention, 126–128
modeling, 23–25
object-oriented API advantages, 159
problem domain modeling, 21
UML diagram example, 24f
Keyword definitions, ANSI C, 153–154

L

Lambert Conformal Conic, adapter pattern, 95
Language APIs, definition, 12
Language barrier, and scripting, 333
Language compatibility, and scripting, 331–332
LaTeX
documentation output, 275–276
Doxygen, 281
Law of Demeter (LoD), class design, 140–141
Lazy initialization, singleton vs. monostate, 83
Lazy instantiation
definition, 185
proxy pattern, 93
singleton thread safety, 80–81
templates, 185
Lcov
example, 324f
testing tools, 324
Legacy code
code coverage, 324–325
Façade pattern, 98
libjpeg library, image APIs, 12
libpng library
adapter pattern, 95
image APIs, 12
Libraries (general)
API example, 2f
C++ API elements, 3
static vs. dynamic, 365
Library Size, definition, 210
libtiff library, image APIs, 12
License information, as documentation type, 277–280
License restrictions, API avoidance, 10
Life cycle, API, 249–250, 249f
Lifetime management, definition, 60
Linden Lab (LL)
constant declarations, 218
C++−specific APIs, 173
Line coverage, testing tools, 323
Linux
AMD CodeAnalyst, 238
APIs in C++, 3
architecture constraints, 123
Boost Python, 338, 340
caching, 29
Callgrind, 238
code coverage, 324
Doxygen, 281
GNU GPL License, 278–279
GUI APIs, 13
Helgrind/DRD, 240
Intel VTune, 237
memory-based analysis, 239
multithreading analysis, 239, 240
numbering schemes, 243
Open SpeedShop, 238
OProfile, 238
performance, 216
SWIG wrappings, 351–352
Sysprof, 238
Linux Kernel API
ANSI C API, 154
bug tracking, 325
as flat API, 152
Second Life Viewer architecture, 14f
version numbers, 244
Liskov Substitution Principle (LSP)
class design, 135–139
composition, 138–139
private inheritance, 137
LLSD, data-driven APIs, 168
Load testing, definition, 294
Localization, testable code writing, 318
Logging domains, key objects, 126
Logical hiding
definition, 28
implementation details, 26–28
Pimpl, 67
Loki, template-based APIs, 161
Longevity, and API code robustness, 7
Lua
MIT/X11 license, 278–279
and SWIG, 334

M

Mac OS X
APIs in C++, 3
architecture constraints, 123
Boost Python, 338, 340
Callgrind, 238
DTrace, 238
gprof, 238
GUI APIs, 13
Helgrind/DRD, 240
Plugin Manager, 370, 372
redundant #include guards, 215
SDKs and APIs, 15
Second Life Viewer architecture, 14f
TotalView MemoryScape, 239
Valgrind, 239
“Winnebago” headers, 212
Macros
assertions, 313
backward compatibility, 260
coding conventions, 208
contract programming, 315
and #define for constants, 200–201
Google Mock, 309–310
internationalization, 318
naming conventions, 208
playback functionality, 317
Plugin API, 367
Plugin versioning, 373
private code testing, 311
scripting, 331
and symbol export, 206–207
vs. template-based APIs, 162
test harnesses, 319
Maintenance
API life cycle, 250
and backward compatibility
API reviews, 262
deprecating functionality, 259–261
functionality addition, 256–257
functionality changing, 257–259
overview, 256–261
removing functionality, 261
test suites, 293
Major version number, definition, 242
Manager classes
and coupling, 58–59, 58f, 59f
singleton, 77
singleton vs. monostate, 84
Maya, array references, 235
Member functions
backward compatibility, 256–257
function design, 142
naming, 143–144
operator overloading, 191–193
private code testing, 311
Member operators, vs. free operators, 191–193
Member variables
class coupling reduction, 54–55
hiding, 28–31
and initialization lists, 221
memory optimization, 221, 222t, 224
and method hiding, 31
Memory-based analysis, API performance, 238–239
Memory management, API resource allocation, 49–50
Memory model semantics, API consistency, 43
Memory optimization
API performance, 221–225, 222f
member variables, 222t
memory layout, 226f
Memory ownership, definition, 304
Memory performance, analysis tools, 239
menvshared, architecture patterns, 130b
Metadata
internal vs. external, 365
and Plugin Manager, 370
Method comments, Doxygen, 286
Microsoft .NET languages
and COM automation, 335
web development, 8
Python bindings, 337
Microsoft Visual Studio
symbol export, 206
version numbers, 243
Middleware services, and APIs, 16
Minimal completeness
convenience APIs, 37–39, 39f
overpromising, 35
overview, 34–39
virtual functions, 36–37
Minor version number, definition, 242
Misuse considerations, API quality, 40–42
MIT/X11, FLOSS license, 278–279
Mock objects
testable code writing, 308–311
unit testing, 297
Model–View–Controller (MVC) pattern
dependencies overview, 100f
overview, 99–101
script-based applications, 330
Modula-3, and SWIG, 334
Modularization
and API code reuse, 8
and API code robustness, 7
Mono
MIT/X11 license, 278–279
plugin security, 365
Monostate design pattern, vs. Singleton, 82–84
Mozilla
bug tracking, 325
performance testing, 300–301, 300f
Mozilla Public License, definition, 278–279
Multithreading performance, analysis, 239–240
Mutex lock, Singleton thread safety, 79–80, 81

N

Name
ATM use case example, 116
class design, 141–142
coding conventions, 208
function design, 143–144
use case template elements, 114
Named Parameter Idiom (NPI), 146, 170
Namespaces
C++−specific APIs, 173–174
and external linkage, 205
naming conventions, 208
Naming conventions
API consistency, 43
language compatibility, 331
Natural language, key objects, 126
Negative testing, definition, 303
NetBeans project, precommit API reviews, 265
Netscape Plugin API (NPAPI), overview, 363b
Netscape Portable Runtime (NSPR)
C++−specific APIs, 173
as flat API, 152
Network protocols, and APIs, 16–17
No license, definition, 278–279
Non-default constructors
explicit keyword, 179
factory methods, 85
function design, 142
Non-friend function
and class coupling, 54–55
function design, 142
Nonfunctional requirements
class design, 133
definition, 111
Nonfunctional testing techniques, types, 294–295
Non-member non-friend functions, class coupling reduction, 55
Nontransferability, technical debt, 107
Non-virtual destructor
and inheritance, 134
and subclassing, 384–385
Non-Virtual Interface (NVI), 37
Notes, use case template elements, 115
Notifications
and coupling, 59–62
and getter/setter routines, 29
NULL pointer
behavioral changes, 271
documentation decisions, 272
error handling, 149–150
factory methods, 85
functional compatibility, 252
resource allocation, 47
in testing, 304

O

Object concept, definition, 132
Object hierarchy
API design, 119
example, 120f
input arguments, 212
Objective-C
Doxygen, 281
language compatibility, 332
Object modeling
abstractions, 124–125
architecture design, 122
class naming, 141
discoverability, 40
key objects, 23, 127
legacy systems, 98
object-oriented API disadvantages, 159
Object-oriented C++ APIs
adapter pattern, 96
advantages, 158–159
and ANSI C API, 154
binary compatibility, 255
callbacks, 61
contract documentation, 270–271
definition, 151
disadvantages, 159
FMOD case study, 159–160
observers, 61
overview, 158–160
style, 151, 158–160
template-based APIs, 161, 164
Object-oriented design
class naming, 141–142
composition vs. inheritance, 138
concept definitions, 132–133
definition, 23
Law of Demeter, 140
UML class diagrams, 23
Object-oriented programming (OOP)
contractor analogy, 2
definition, 158
disadvantages, 159
encapsulation, 26–27, 31
inheritance, 374
template extensions, 385
Observer pattern
definition, 66
implementation, 101–103
overview, 99–104
push vs. pull, 103–104
UML representation, 101f
Observers, and coupling, 59–62
OCAML, and SWIG, 334
Octave, and SWIG, 334
OGRE, 3D graphics APIs, 12
Opaque pointers
ANSI C API, 155
in C, 75–76
and forward compatibility, 256
method hiding, 33
and Pimpl, 67
Open/Closed Principle (OCP), class design, 139–140
OpenGL (GL)
convenience APIs, 38, 39f
C++−specific APIs, 173
Façade pattern, 98
3D graphics APIs, 12
OpenGL Utility Library (GLU)
convenience APIs, 38–39, 39f
Façade pattern, 98
OpenGL Utility Toolkit (GLUT), convenience APIs, 39, 39f
Open Inventor, visitor patterns, 379
OpenJPEG library, Façade pattern, 99
OpenSceneGraph
example, 125f
3D graphics APIs, 12
visitor patterns, 379
Open Source Initiative (OSI), FLOSS licenses, 278
Open SpeedShop, for performance analysis, 238
Operating system (OS) APIs, definition, 11
Operational factors, architecture design, 123
Operation order, testing, 303
Operator compatibility, language issues, 332
Operator overloading
coding conventions, 208
conversion operators, 197–198
vs. default arguments, 200
free/member functions, 191–193
operator addition to class, 193–195
operator categories, 190–191
overview, 190–198
syntax, 195–196, 195t
Operator symmetry, and overloading, 192
Operator syntax, overloading, 195–196, 195t
OProfile, for performance analysis, 238
Optimization, and API code robustness, 7
Organizational factor
architecture design, 123
function design, 142
Orthodox canonical class form, definition, 176
Orthogonality
API ease-of-use, 45–47
definition, 45
Overloadable operators, categories, 190–191
Overloading, virtual functions, 37
Overview documentation, characteristics, 276

P

Package-private, definition, 27
Parabuild, definition, 326
Parallel branches, software branching strategies, 247–248
Parallel development, and API usage, 9–10
Parallel products, software branching strategies, 248–249
Parameter order, API consistency, 43
Parameter testing, definition, 303
Parasoft Insure++, for performance analysis, 239
Partial specialization, templates, 185
Patch version number, definition, 242
PDF
documentation output, 275–276
Doxygen, 281
Peer-to-peer applications, and APIs, 16
Performance testing
definition, 294
example, 300f
overview, 298–301
Perl
and COM automation, 335
and CORBA, 336
vs. C++ web development, 8
extending vs. embedding, 329
Ruby creation, 349
and SWIG, 334
Permissive license, definition, 278
PHP
array references, 235
web development, 8
documentation, 274
Doxygen, 281
and SWIG, 334
Physical hiding
implementation details, 25–26
Pimpl, 67
Pimpl idiom (Pointer to Implementation)
advantages, 73–74
binary compatibility, 255
copy semantics, 71–72, 73
definition, 33, 66
disadvantages, 74
example, 67f
nested implementation class, 71
opaque pointers in C, 75–76
overview, 67–76
smart pointers, 72–73
usage, 67–71
Pixar
API performance approach, 210
API reviews, 263
code testing, 292
design team, 131
extensibility example, 361
menvshared use, 130
script-based applications, 330
Platform compatibility
nonfunctional requirements, 112
and scripting, 330
Platform idioms
API consistency, 44
Pimpl idiom example, 68
Platform independence, API ease-of-use, 51–52
Playback functionality, testable code writing, 317–318
Plugin API
definition, 364
example, 369–370
overview, 367–369
Plugin-based extensibility
benefits, 362–363
Netscape Plugin API, 363b
overview, 361–374
Plugin API, 367–370
plugin implementation, 366
Plugin Manager, 370–372
system design issues, 364–365
versioning, 372–374
Plugin Manager
as Core API component, 364f
definition, 364
generic vs. specialized, 365
overview, 370–372
PngSuite
definition, 298
example, 298f
Pointer vs. reference parameters, 198–199
Pointer symbols, coding conventions, 207
Policy-based templates, for extending, 386–387
Policy decisions, software branching strategies, 246–247
Polymorphism
Boost Python bindings, 345–346
and consistency, 44
cross-language, 333, 345–346, 356–357
CRTP, 387
definition, 133
object-oriented C++ APIs, 151, 158
Ruby bindings with SWIG, 356–357
template-based APIs, 163, 164
template extension, 385
Portability
coding conventions, 208
as test quality, 301
POSIX API, definition, 11
Postcondition
ATM use case example, 116
contract programming, 270, 315
use case template elements, 115
Precommit API reviews, overview, 265
Precondition
contract programming, 269, 315
use case template elements, 115
Preprocessor symbols, overloadable operators, 190–191
Prerelease
API life cycle, 250
API reviews, 263–264
Primitiveness, convenience APIs, 37
Principle of Least Knowledge, See Law of Demeter (LoD)
Private access level
definition, 27, 27f
implementation method hiding, 32–33
Private code
API design, 187
inlining, 228
testing, 311–313
Private inheritance
adapter pattern, 95
class design, 133, 137
and composition, 138
OOP concepts, 132
usage, 134
Problem domain
API design elements, 118
architecture design, 121, 125
class naming, 141
functional requirements, 111
modeling, API qualities
abstraction, 21–23, 22f
key objects, 23–25, 24f
and performance, 209
platform independence, 51
use cases, 114
Process standards, coding conventions, 208
Product owner, prerelease API reviews, 263
Properties, key objects, 126
Proprietary license, definition, 277
Protected access level
definition, 27, 27f
implementation method hiding, 32–33
Prototypes, key objects, 126
Proxy API, record/playback functionality, 317
Proxy design patterns
definition, 66
overview, 91–94
UML diagram, 91f
Public access level
definition, 27, 27f
implementation method hiding, 32–33
Public headers
API life cycle, 250
automated documentation, 274
data-driven APIs, 167–168
#define for constants, 201
explicit instantiation API design, 189
factory methods, 88
forward declarations, 214
implicit instantiation API design, 186
inlining, 227
Pimpl idiom, 66, 67, 71, 73
platform independence, 51
private members, 33
source compatibility, 253
template-based APIs, 164
Public symbols
namespaces, 173
private code testing, 313
“Winnebago” headers, 212
Pull-based observers, vs. push-based, 103–104
Push-based observers, vs. pull-based, 103–104
Python
See also Boost Python
API extension, 341–343
and API qualities, 21
array references, 235
and COM automation, 335
web development, 8
Doxygen, 281
error handling, 148
extending vs. embedding, 329
Open SpeedShop, 238
Plugins, 366
scripting and language barrier, 333
variant argument lists, 168
version numbers, 243
Python-SIP, features, 334–335
PyUnit, 296

Q

Qt API
automated GUI testing, 294
backward compatibility functionality, 261
consistency, 43
and copy on write, 232
C++−specific APIs, 173
data-driven APIs, 166
documentation, 274, 275f
extensibility via inheritance, 375, 375f
GUI APIs, 13
MVC, 100
Python-SIP, 334–335
scripting and language barrier, 333
Quality assurance (QA)
integration testing, 298
record/playback functionality, 317
testing relationship, 304–305
QuickTime (Apple), 363
QVariant, data-driven APIs, 168

R

Random access, and iterators, 234–235
Rational PureCoverage, testing tools, 324
Record functionality, testable code writing, 317–318
Redundancy
API orthogonality, 47
and coupling, 56–57
#include guards, 215–217, 215t
Reentrancy, definition, 60
Reference vs. pointer parameters, 198–199
Reference symbols, coding conventions, 207
Regression testing, definition, 303
Relational operators, adding to class, 193–194
Release notes, as documentation type, 277
Resource Acquisition Is Initialization (RAII), 49–50
Resource allocation, API ease-of-use, 47–50
Resource sharing, proxy patterns, 93
Return values
backward compatibility, 258
C function calls, 156–157
const correctness, 182–183
conversion operators, 198
documentation, 268, 271, 272, 286
optimization, 179, 235
Ruby API tuning, 352
testing, 303, 317
Review process, software branching strategies, 248
Revolution strategy, definition, 108
Rigidity, technical debt, 107
R language, and SWIG, 334
ROBODoc, documentation generation, 276
Role domains, key objects, 126
RTF, Doxygen, 281
Ruby
and COM automation, 335
and CORBA, 336
extending vs. embedding, 329
inheritance, 135
language compatibility, 331
MIT/X11 license, 278–279
Plugins, 366
popularity, 329
script bindings with SWIG
API extension, 353–354
API tuning, 352–353
code example, 357–359
constructors, 353
cross-language polymorphism, 356–357
example, 350f
inheritance, 354–356
overview, 349–359
wrappings, 350–351
scripting advantages, 330
and SWIG, 334
Run-time memory overhead, definition, 209
Run-time speed, definition, 209

S

Safari (Apple), 299, 363
Sampling, time-based performance analysis, 236
Sapir–Whorf hypothesis, 331
Scalability, nonfunctional requirements, 112
Scalability testing, definition, 294
Scene graph
array references, 235
hierarchy example, 379f
nodes example, 379f
OpenSceneGraph API, 125f
3D graphics APIs, 12
visitor pattern, 378–379
Scoped pointers
definition, 48
and Pimpl, 72–73
Scoping
and #define, 201
templates vs. macros, 162
Script-based applications, scripting advantages, 330
Script-binding technologies
Boost Python, 334
COM automation, 335–336
CORBA, 336–337
overview, 333–337
Python-SIP, 334–335
SWIG, 334
Scripting
advantages, 330–331
architectural patterns, 130
Boost Python bindings
API extension, 341–343
code example, 347–349
construction, 338
constructors, 341
cross-language polymorphism, 345–346
inheritance, 344–345
iterator support, 346–347
overview, 337–349, 337f
wrappings, 338–341
and C++ APIs, 8
error handling, 148
extending vs. embedding, 329–330
language barrier, 333
language compatibility, 331–332
overview, 329
plugin implementation, 366
and plugin security, 365
and QA, 305
Ruby with SWIG
API extension, 353–354
API tuning, 352–353
code example, 357–359
constructors, 353
cross-language polymorphism, 356–357
example, 350f
inheritance, 354–356
overview, 349–359
wrappings, 350–351
Scrum, 304
Search, documentation usability, 280
Second Life
architecture diagram, 14, 14f
C++−specific APIs, 173
Façade pattern, 99
monostate design pattern, 83–84
open-/closed-source APIs, 15t
time-based performance analysis, 236, 237f
Security domains, key objects, 126
Security issues
architecture constraints, 123
functionality deprecation, 260
functionality removal, 261
nonfunctional requirements, 112
patch version, 242
plugin system design, 365
Security testing
compliance assurance, 292
definition, 294
private code, 312
test focus, 304
Self-test method, example, 311–312
Separation Model, templates, 187
Session state, vs. Singleton, 84–85
Shared libraries, See dynamic libraries
Shared pointers
copy on write, 229–231
definition, 48
and Pimpl, 72–73
template extensions, 385
Shark (Apple), for performance analysis, 238
Shlaer–Mellor domains, key objects, 126
Short examples, as documentation type, 276
Signals and slots, and coupling, 62
Simple examples, as documentation type, 276
Simplified Wrapper and Interface Generator (SWIG)
features, 334
for Ruby bindings
API extension, 353–354
API tuning, 352–353
code example, 357–359
constructors, 353
cross-language polymorphism, 356–357
example, 350f
inheritance, 354–356
overview, 349–359
wrappings, 350–351
Singleton design pattern
definition, 66
vs. dependency injection, 81–82
implementation in C++, 77–79
vs. monostate, 82–84
overview, 76–85
vs. session state, 84–85
thread safety, 79–81
UML diagram, 76f
Size-based types, and memory optimization, 223
Smalltalk language
and CORBA, 336
encapsulation, 27
OOP origins, 158
and Ruby, 349
Smart pointers
API resource allocation, 48
architecture constraints, 124
class design, 133
implicit instantiation, 185–186
Pimpl idiom, 72–73
policy-based templates, 386
Soak testing, definition, 294
SOAP, and COM automation, 335
Software branching strategies
file formats, 248–249
overview, 245–249
parallel branches, 247–248
parallel products, 248–249
policies, 246–247
product releases, 246f
schemes, 246
Software Design Engineer in Test (SDET), duties, 305
Software Development Kit (SDK), and APIs, 15b
Software Test Engineer (STE), duties, 305
Solaris
memory-based analysis, 239
multithreading analysis, 240
Source compatibility
adding functionality, 256
changing functionality, 257–258
overview, 252–253
Source control management (SCM), software branching strategies, 247
Specialization
class hierarchy, 119
CRTP, 387
explicit instantiation, 184, 187
lazy instantiation, 185
template arguments, 184
templates, 185, 189
Specialized Plugin Manager, plugin system design, 365
Squish, automated GUI testing, 294
Stability
and API life cycle, 250
and API reviews, 262
convenience APIs, 37
data-driven APIs, 167
overview documentation, 276
plugin-based extensibility, 362
plugin future proofing, 362
and technical debt, 107
as test quality, 301
and version numbers, 243
Stack declaration, template-based API, 161
Stakeholder
ATM use case example, 116
use case template elements, 115
Standard C Library
and API design, 4
and consistency, 43
conversion operators, 197–198
as flat API, 152
Second Life architecture, 14f
Standard Template Library (STL)
API consistency, 43–44
as C++ API, 4
for extending, 385
forward declarations, 214
and inheritance, 376–377
input arguments via const reference, 211–212
iterators, 234
language APIs, 12
plugin implementation, 366
template-based APIs, 161
Startup time
definition, 210
performance testing, 300–301, 300f
Statement coverage, testing tools, 323
Static declaration, and external linkage, 205
Static initialization
singleton thread safety, 81
and startup time, 210
Static libraries
binary compatibility, 253
C++ API elements, 3
C++ APIs, 3
vs. dynamic, 365
plugins, 361
plugin system design, 365
Stream operators, adding to class, 194
Structs
ANSI C API, 155
coding conventions, 208
definition, 153
flat C APIs, 151–152
implementation detail hiding, 26–27
keyword definition, 153
logical hiding, 26–27
template-based APIs, 161
Structural design patterns
API wrapping, 91
architecture classifications, 129
examples, 65–66
Stub objects
testable code writing, 308–311
unit testing, 297
Subclassing
constructors and assignment, 176
prohibiting, 384–385
virtual functions, 37
Symbian platform
precommit API reviews, 265
public interface change request process, 264f
Symbol export, 204–207
Symbol names
binary compatibility, 253
C function calls, 156–157
default arguments, 199
#define for constants, 201
flat C APIs, 152
namespaces, 174
Symbol table
#define for constants, 201
forward declarations, 213–214
Synchronization
bug example, 50
and getter/setter routines, 29
multithreading analysis, 240
Sysprof, for performance analysis, 238

T

Tangible domains, key objects, 126
Task focus, documentation usability, 281
Tcl
and CORBA, 336
and SWIG, 334
TeamCity, definition, 326
Technical debt
accruing, 106–107
paying back, 107–109
Technical lead, prerelease API reviews, 263
Template arguments, definition, 184
Template-based APIs
advantages, 163
definition, 151
disadvantages, 164
example, 161–162
vs. macros, 162
overview, 160–164
Template parameters, definition, 184
Templates
API consistency, 44
backward compatibility, 258
class design, 133
explicit instantiation API design, 187–190
for extending
CRTP, 387–389
overview, 385–389
policy-based templates, 386–387
implicit instantiation API design, 185–187
and inlining, 227
overview, 183–190
terminology, 184–185
Template Unit Test (TUT), overview, 321
Terminology in documentation, 280
Testable code
assertions, 313–314
contract programming, 314–317
internalization support, 318
private code, 311–313
record/playback functionality, 317–318
scripting advantages, 331
stub/mock objects, 308–311
test-driven development, 305–307
writing, 305–318
Test-driven development (TDD), overview, 305–307
Test harnesses
Boost Test, 320
CppUnit, 319
definition, 318
examples, 319–322
Google Test, 321
TUT, 321
Testing
API qualities, 62–63
automated, See Automated testing
data-driven APIs, 167
integration testing, 297–298
overview, 291
performance testing, 298–301
PngSuite example, 298f
reasons, 291–293
types, 293–301
unit testing, 295–297
untested code cost, 293b
use cases, 116
Testing tools
bug tracking, 325–326
categories, 318–326
code coverage, 322–325, 324f
continuous build systems, 326, 327f
test harnesses, 319–322
Test writing
focus, 304
overview, 301–305
QA relationship, 304–305
qualities, 301–302
techniques, 302–304
TeX document processing system, version numbering, 243
Threading Build Blocks (TBB), C++−specific APIs, 174
Thread safety
proxy patterns, 93
singleton design pattern, 79–81
Three-dimensional graphics APIs, definition, 12
Three Laws of Interfaces, error handling, 146–147
TIFF files, image APIs, 12
Time-based analysis
example, 237f
performance, 236–238
Tinderbox
definition, 326
example, 327f
TotalView MemoryScape, for performance analysis, 239
Trigger
ATM use case example, 116
use case template elements, 115
“Trunk” code line, software branching strategies, 246, 248
Tutorials, as documentation type, 276–277
TwinText, documentation generation, 276
Type checking
C language, 154b
#define for constants, 201
templates vs. macros, 162
Type coercions
Boost Python, 334
class design, 133
conversion operators, 198
typedef keyword (general)
API design, 189
definition, 153
documentation, 272
flat C APIs, 151–152
forward compatibility, 256
forward declarations, 214
naming conventions, 208
policy-based templates, 387
template-based API, 162
Type safety, and enum, 202

U

Ubuntu, numbering schemes, 243
Unary operators, overloading, 190
Unified Modeling Language (UML)
adapter pattern, 94f
API abstraction, 22, 22f
API key objects, 24, 24f
architecture design communication, 130
class diagrams, 23b
diagram types, 128f
Façade pattern, 97f
key objects, 127
manager classes, 58
Observer pattern, 101f
proxy patterns, 91f
Singleton design pattern, 76f
visitor patterns, 381f
Unintentional debt, definition, 106–107
Unions
ANSI C API, 155
data-driven APIs, 169
keyword definition, 153
memory optimization, 223
variant argument lists, 169
Unit testing
JUnit, 296b
overview, 295–297
and TDD, 307
Universally unique identifier (UUID)
API key object modeling, 24
COM automation, 335
and coupling, 59–60
Universal Transverse Mercator, adapter pattern, 95
UNIX
CORBA, 336
Doxygen, 281
layers of APIs, 11
memory optimization, 223
Plugin Manager, 370
TotalView MemoryScape, 239
Usability
API reviews, 262
architecture constraints, 123–124
documentation, 280–281
nonfunctional requirements, 112
scripting advantages, 331
Use cases
Agile development, 117–118
creation, 113–118
development, 114
performance testing, 299
requirements, 117–118
templates, 114–115
testing, 292
writing, 115–116
User contributions, as documentation type, 276

V

Valgrind, for performance analysis, 239
Validation, and getter/setter routines, 29
Variant argument lists, data-driven APIs, 168–170
Versioning
API creation, 244–245
API life cycle, 249–250, 249f
API reviews
overview, 261–265
precommit, 265
prerelease, 263–264
purpose, 262–263
backward compatibility, 251
backward compatibility maintenance
depracating functionality, 259–261
functionality addition, 256–257
functionality changing, 257–259
overview, 256–261
removing functionality, 261
binary compatibility, 253–255
compatibility levels, 250–256
forward compatibility, 255–256
functional compatibility, 251–252
overview, 241
plugin-based extensibility, 362, 372–374
plugin system design, 365
software branching strategies
file formats, 248–249
overview, 245–249
parallel branches, 247–248
parallel products, 248–249
policies, 246–247
product releases, 246f
schemes, 246
source compatibility, 252–253
Version number
ATM use case example, 116
esoteric schemes, 243–244
overview, 241–245
progression, 242f
significance, 241–243
use case template elements, 114
version API creation, 244–245
Virtual constructors, Factory Methods, 85
Virtual destructor
coding conventions, 208
compiler-generated functions, 176–177
and inheritance, 344, 374–375, 376
stub objects, 308–309
Virtual functions
backward compatibility, 256–257
class design, 134
and memory optimization, 223
and minimal completeness, 36–37
Observer pattern, 103
virtual inheritance, diamond problem, 135
Virtual Reality Modeling Language (VRML), visitor patterns, 379
Visibility
and coupling, 53
encapsulation, 27
symbol export, 204, 206
UML class diagrams, 23
Visitor pattern
and inheritance, 378–384
UML diagram, 381f
Visual Basic, and COM automation, 335
void keyword, definition, 154
void* pointers
data-driven APIs, 169
Plugin Manager, 365
template extension, 385

W

Walkthroughs, as documentation type, 276
Weak pointers, definition, 48
Web development, and C++ APIs, 8b
Web services, data-driven APIs, 165–166
White box testing
definition, 293
and SDET, 305
unit testing as, 295
Wiki pages
architecture design communication, 130
documentation types, 274
Windows (Win32)
architecture constraints, 123
backward compatibility, 258
code coverage, 324
definition, 11
elements, 4
as flat API, 152
GUI APIs, 13
Intel VTune, 237
memory-based analysis, 239
Second Life Viewer architecture, 14f
“Winnebago” headers, 212
“Winnebago” headers, #include dependency minimization, 212–213
Working demos, as documentation type, 276
Wrapping patterns
Boost Python bindings, 338–341
overview, 91–99
with SWIG, 350–351
wxWidgets library, GUI APIs, 13

X

XML (Extensible Markup Language)
API examples, 13–14, 15t
code reuse, 7–8
data-driven web services, 165–166
Doxygen, 281
file formats, 248
Google Test reports, 321
Plugin Manager, 370, 371–372
Python, 337
record/playback functionality, 317
software branching strategies, 248
test harnesses, 319
X/Motif, GUI APIs, 13
xUnit, 296