API Design for C++. 2 Ed

Front Cover....1

API Design for C++....2

API Design for C++....4

Copyright....5

Contents....6

Author biography....12

Foreword....14

Preface....16

Preface to the second edition....16

What is application programming interface design?....16

Why should you read this book?....17

Who is the target audience?....18

Focusing on C++....18

Conventions....19

Book website....20

Acknowledgments....22

1 - Introduction....24

What are APIs?....24

Contracts and contractors....24

APIs in C++....26

What's different about API design?....27

Why should you use APIs?....30

More robust code....30

Code reuse....31

Parallel development....33

When should you avoid APIs?....34

API examples....36

Layers of APIs....36

A real-life example....39

Libraries, frameworks, and software development kits....40

File formats and network protocols....42

About this book....44

2 - Qualities....48

Model the problem domain....48

Provide a good abstraction....48

Model the key objects....50

Solve the core problems....52

Hide implementation details....54

Physical hiding: Declaration versus definition....54

Logical hiding: Encapsulation....56

Hide member variables....58

Hide implementation methods....61

Hide implementation classes....63

Minimally complete....65

Don't overpromise....66

Don't repeat yourself....67

Convenience APIs....68

Add virtual functions judiciously....71

Easy to use....73

Discoverable....73

Difficult to misuse....74

Consistent....77

Orthogonal....80

Robust resource allocation....83

Platform independent....86

Loosely coupled....88

Coupling by name only....90

Reducing class coupling....91

Intentional redundancy....92

Manager classes....94

Callbacks, observers, and notifications....97

Callback functions....98

Observers....100

Notifications....102

Stable, documented, and tested....103

3 - Patterns....104

Pimpl idiom....106

Using pimpl....106

Copy semantics....110

Pimpl and smart pointers....111

Advantages of pimpl....112

Disadvantages of pimpl....113

Opaque pointers in C....114

Singleton....116

Implementing singletons in C++....117

Singletons and thread safety....119

Singleton versus dependency injection....119

Singleton versus Monostate....121

Singleton versus session state....123

Factory Methods....124

Abstract base classes and interfaces....124

Simple factory example....126

Extensible factory example....128

API wrapping patterns....130

The Proxy pattern....131

The Adapter pattern....133

The Façade pattern....136

Observer pattern....138

Model–View–Controller....139

Implementing the Observer pattern....140

Push versus pull observers....143

4 - Design....146

A case for good design....146

Accruing technical debt....147

Paying back the debt....149

Design for the long term....151

Gathering functional requirements....152

What are functional requirements?....153

Example functional requirements....154

Maintaining the requirements....155

Creating use cases....155

Developing use cases....156

Use case templates....157

Writing good use cases....158

Requirements and agile development....160

Elements of API design....162

Architecture design....165

Developing an architecture....166

Architecture constraints....167

Identifying the major abstractions....169

Inventing the key objects....171

Architectural patterns....174

Communicating the architecture....176

Class design....177

Object-oriented concepts....178

Class design options....179

The SOLID principles....180

Using inheritance....180

Liskov substitution principle....182

Private inheritance....184

Composition....185

The open/closed principle....186

The Law of Demeter....188

Class naming....189

Function design....190

Function design options....190

Function naming....191

Function parameters....192

Error handling....196

5 - Styles....202

Flat C APIs....203

ANSI C features....204

Benefits of an ANSI C API....205

Writing an API in ANSI C....206

Calling C functions from C++....208

Case study: FMOD C API....209

Object-oriented C++ APIs....209

Advantages of object-oriented APIs....210

Disadvantages of object-oriented APIs....210

Case study: FMOD C++ API....211

Template-based APIs....212

An example template-based API....212

Templates versus macros....213

Advantages of template-based APIs....214

Disadvantages of template-based APIs....215

Functional APIs....216

Functional programming concepts....216

An example functional API....218

Advantages of functional APIs....219

Disadvantages of functional APIs....219

Data-driven APIs....220

Advantages of data-driven APIs....222

Disadvantages of data-driven APIs....224

Supporting variant argument lists....224

Case study: FMOD data-driven API....225

Data-driven Web services....226

Idempotency....227

6 - C++ usage....232

Namespaces....232

Constructors and assignment....234

Defining constructors and assignment....236

The explicit keyword....238

Const correctness....239

Method const correctness....239

Parameter const correctness....241

Return value const correctness....242

Templates....243

Template terminology....243

Implicit instantiation API design....246

Explicit instantiation API design....247

Operator overloading....250

Overloadable operators....251

Free operators versus member operators....252

Adding operators to a class....254

Operator syntax....256

Conversion operators....259

Function parameters....259

Pointer versus reference parameters....259

Default arguments....261

Avoid #define for constants....262

Avoid using friends....265

Exporting symbols....267

Coding conventions....270

7 - C++ revisions....274

Which C++ revision to use....274

C++11 API features....275

Move constructors and the Rule of Five....275

Default and deleted functions....279

Object construction....281

Initializer list constructors....284

Smart pointers....284

Enum classes....287

Override and final specifiers....289

The noexcept specifier....292

Inline namespaces....293

Type aliases with using....295

User-defined literals....296

Alternate function style....298

Tuples....299

Constant expressions....300

The nullptr keyword....302

Variadic templates....303

Migrating to C++11....305

C++14 API features....306

The auto return type....307

The deprecated attribute....308

Variable templates....309

Const expression improvements....310

Binary literals and digit separators....311

Migrating to C++14....311

C++17 API features....312

Inline variables....312

String views....314

Optional....316

Any....319

Variant....321

Nested namespaces....323

Fold expressions....324

Checking for header availability....326

Byte type....328

The maybe_unused attribute....328

Migrating to C++17....330

C++20 API features....330

Modules....331

Named Modules....331

Header units....333

The spaceship operator....334

Constraints and concepts....339

Abbreviated function templates....341

The consteval specifier....342

The constinit specifier....343

Migrating to C++20....344

C++23 API features....345

Expected values....346

Multidimensional subscript operator....347

Preprocessor directives....348

Migrating to C++23....350

8 - Performance....352

Pass input arguments by const reference....354

Minimize #include dependencies....356

Avoid “Winnebago” headers....356

Forward declarations....356

Redundant #include guards....359

Declaring constants....361

The constexpr, consteval, and constinit keywords....363

Initialization lists....364

Memory optimization....366

Don't inline functions until you need to....371

Copy on write....374

Iterating over elements....379

Iterators....379

Random access....380

Array references....381

Extern templates....382

Performance analysis....383

Time-based analysis....384

Memory-based analysis....387

Multithreading analysis....388

9 - Concurrency....390

Multithreading with C++....390

Terminology....392

Data races and race conditions....392

Thread safety....393

Reentrancy....394

Asynchronous tasks....395

Parallelism....395

Accessing shared data....396

Stateless APIs....396

Initializing shared data....398

Synchronized data access....400

Concurrent API design....401

Concurrency best practices....401

Thread-Safe Interface pattern....402

10 - Versioning....406

Version numbers....406

Version number significance....406

Esoteric numbering schemes....408

Creating a version API....409

Software branching strategies....411

Branching strategies....411

Branching policies....411

APIs and parallel branches....413

File formats and parallel products....414

Life cycle of an API....415

Levels of compatibility....416

Backward compatibility....417

Functional compatibility....418

Source compatibility....418

Binary/application binary interface compatibility....419

Binary incompatible API changes....420

Binary compatible API changes....421

Forward compatibility....422

How to maintain backward compatibility....424

Adding functionality....424

Changing functionality....425

Deprecating functionality....427

Removing functionality....429

Inline namespaces for versioning....430

API reviews....431

The purpose of API reviews....432

Prerelease API reviews....433

Precommit API reviews....435

11 - Documentation....438

Reasons to write documentation....438

Defining behavior....439

Documenting the interface's contract....441

Communicating behavioral changes....443

What to document....444

Types of documentation....446

Automated API documentation....446

Overview documentation....448

Examples and tutorials....449

Release notes....450

License information....451

Documentation usability....453

Inclusive language....455

Using Doxygen....457

The configuration file....457

Comment style and commands....458

API comments....459

File comments....460

Class comments....461

Method comments....462

Enum comments....463

Sample header with documentation....463

12 - Testing....466

Reasons to write tests....466

Types of API testing....469

Unit testing....470

Integration testing....473

Performance testing....475

Writing good tests....477

Qualities of a good test....477

What to test....479

Focusing the testing effort....481

Working with quality assurance....481

Writing testable code....482

Test-driven development....482

Stub and mock objects....485

Testing private code....489

Using assertions....492

Contract programming....493

Record and playback functionality....496

Supporting internationalization....498

Automated testing tools....499

Test harnesses....499

Code coverage....503

Bug tracking....506

Continuous build system....507

13 - Objective-C and Swift....510

Interface design in C++ and Objective-C....510

Data hiding in Objective-C....512

Objective-C behind a C++ API....514

C++ behind an Objective-C API....517

C++ behind a Swift API....520

14 - Scripting....524

Adding script bindings....524

Extending versus embedding....524

Advantages of scripting....525

Language compatibility issues....527

Crossing the language barrier....528

Script binding technologies....529

Boost Python....529

Simplified wrapper and interface generator....530

Python-SIP....530

Component object model automation....531

Common object request broker architecture....532

Adding Python bindings with Boost Python....533

Building Boost Python....533

Wrapping a C++ API with Boost Python....534

Constructors....536

Extending the Python API....537

Inheritance in C++....539

Cross-language polymorphism....541

Supporting iterators....542

Putting it all together....543

Adding Ruby bindings with SWIG....544

Wrapping a C++ API with SWIG....545

Tuning the Ruby API....547

Constructors....548

Extending the Ruby API....548

Inheritance in C++....549

Cross-language polymorphism....551

Putting it all together....552

15 - Extensibility....556

Extending via plugins....556

Plugin model overview....557

Plugin system design issues....560

Implementing plugins in C++....562

The plugin API....563

An example plugin....565

The Plugin manager....567

Plugin versioning....570

Extending via inheritance....572

Adding functionality....572

Modifying functionality....573

Inheritance and the standard library....574

Inheritance and enums....576

The Visitor pattern....577

Extending via templates....583

Policy-based templates....583

The curiously recurring template pattern....585

A: Libraries....588

Static libraries....588

Dynamic libraries....589

Dynamic libraries as plugins....591

Importing and exporting functions....592

The Dynamic Link Library entry point....593

Creating libraries on Windows....594

Useful Windows utilities....595

Loading plugins on Windows....595

Creating static libraries on Linux....596

Creating dynamic libraries on Linux....597

Shared library entry points....598

Useful Linux utilities....599

Loading plugins on Linux....600

Finding dynamic libraries at run time....601

Creating static libraries on macOS....602

Creating dynamic libraries on macOS....602

Frameworks on macOS....603

Text-based InstallAPI....604

Finding dynamic libraries at run time....605

References....606

Index....612

A....612

B....616

C....618

D....625

E....627

F....628

G....630

H....631

I....631

J....633

K....633

L....633

M....634

N....636

O....636

P....638

Q....640

R....640

S....641

T....644

U....646

V....646

W....647

X....648

Z....648

Back Cover....650

API Design for C++, Second Edition provides a comprehensive discussion of Application Programming Interface (API) development, from initial design through implementation, testing, documentation, release, versioning, maintenance, and deprecation. It is the only book that teaches the strategies of C++ API development, including interface design, versioning, scripting, and plug-in extensibility. Drawing from the author's experience on large scale, collaborative software projects, the text offers practical techniques of API design that produce robust code for the long-term. It presents patterns and practices that provide real value to individual developers as well as organizations. The Second Edition includes all new material fully updated for the latest versions of C++, including a new chapter on concurrency and multithreading, as well as a new chapter discussing how Objective C++ and C++ code can co-exist and how a C++ API can be accessed from Swift programs. In addition, it explores often overlooked issues, both technical and non-technical, contributing to successful design decisions that produce high quality, robust, and long-lived APIs. It focuses on various API styles and patterns that will allow you to produce elegant and durable libraries. A discussion on testing strategies concentrates on automated API testing techniques rather than attempting to include end-user application testing techniques such as GUI testing, system testing, or manual testing.

• Teaches the strategies of C++ API development, including design, versioning, documentation, testing, scripting, and extensibility
• Includes extensive code examples that illustrate each concept, with fully functional examples and working source code for experimentation available online
• Covers various API styles and patterns, with a focus on practical and efficient designs for large-scale, long-term projects
• Includes updated URLs and ensures all code examples continue to work with modern compilers and supporting tools