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)
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.147.61.49