API Design for C++.

Format:

Book

Author/Creator:

Reddy, Martin.

Language:

English

Subjects (All):

Application program interfaces (Computer software).

C++ (Computer program language).

Physical Description:

1 online resource (650 pages)

Edition:

2nd ed.

Place of Publication:

San Diego : Elsevier Science & Technology, 2024.

Summary:

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.

Contents:

Front Cover

API Design for C++

Copyright

Contents

Author biography

Foreword

Preface

Preface to the second edition

What is application programming interface design?

Why should you read this book?

Who is the target audience?

Focusing on C++

Conventions

Book website

Acknowledgments

1 - Introduction

What are APIs?

Contracts and contractors

APIs in C++

What's different about API design?

Why should you use APIs?

More robust code

Code reuse

Parallel development

When should you avoid APIs?

API examples

Layers of APIs

A real-life example

Libraries, frameworks, and software development kits

File formats and network protocols

About this book

2 - Qualities

Model the problem domain

Provide a good abstraction

Model the key objects

Solve the core problems

Hide implementation details

Physical hiding: Declaration versus definition

Logical hiding: Encapsulation

Hide member variables

Hide implementation methods

Hide implementation classes

Minimally complete

Don't overpromise

Don't repeat yourself

Convenience APIs

Add virtual functions judiciously

Easy to use

Discoverable

Difficult to misuse

Consistent

Orthogonal

Robust resource allocation

Platform independent

Loosely coupled

Coupling by name only

Reducing class coupling

Intentional redundancy

Manager classes

Callbacks, observers, and notifications

Callback functions

Observers

Notifications

Stable, documented, and tested

3 - Patterns

Pimpl idiom

Using pimpl

Copy semantics

Pimpl and smart pointers

Advantages of pimpl

Disadvantages of pimpl

Opaque pointers in C

Singleton

Implementing singletons in C++

Singletons and thread safety

Singleton versus dependency injection.

Singleton versus Monostate

Singleton versus session state

Factory Methods

Abstract base classes and interfaces

Simple factory example

Extensible factory example

API wrapping patterns

The Proxy pattern

The Adapter pattern

The Façade pattern

Observer pattern

Model-View-Controller

Implementing the Observer pattern

Push versus pull observers

4 - Design

A case for good design

Accruing technical debt

Paying back the debt

Design for the long term

Gathering functional requirements

What are functional requirements?

Example functional requirements

Maintaining the requirements

Creating use cases

Developing use cases

Use case templates

Writing good use cases

Requirements and agile development

Elements of API design

Architecture design

Developing an architecture

Architecture constraints

Identifying the major abstractions

Inventing the key objects

Architectural patterns

Communicating the architecture

Class design

Object-oriented concepts

Class design options

The SOLID principles

Using inheritance

Liskov substitution principle

Private inheritance

Composition

The open/closed principle

The Law of Demeter

Class naming

Function design

Function design options

Function naming

Function parameters

Error handling

5 - Styles

Flat C APIs

ANSI C features

Benefits of an ANSI C API

Writing an API in ANSI C

Calling C functions from C++

Case study: FMOD C API

Object-oriented C++ APIs

Advantages of object-oriented APIs

Disadvantages of object-oriented APIs

Case study: FMOD C++ API

Template-based APIs

An example template-based API

Templates versus macros

Advantages of template-based APIs

Disadvantages of template-based APIs

Functional APIs

Functional programming concepts.

An example functional API

Advantages of functional APIs

Disadvantages of functional APIs

Data-driven APIs

Advantages of data-driven APIs

Disadvantages of data-driven APIs

Supporting variant argument lists

Case study: FMOD data-driven API

Data-driven Web services

Idempotency

6 - C++ usage

Namespaces

Constructors and assignment

Defining constructors and assignment

The explicit keyword

Const correctness

Method const correctness

Parameter const correctness

Return value const correctness

Templates

Template terminology

Implicit instantiation API design

Explicit instantiation API design

Operator overloading

Overloadable operators

Free operators versus member operators

Adding operators to a class

Operator syntax

Conversion operators

Pointer versus reference parameters

Default arguments

Avoid #define for constants

Avoid using friends

Exporting symbols

Coding conventions

7 - C++ revisions

Which C++ revision to use

C++11 API features

Move constructors and the Rule of Five

Default and deleted functions

Object construction

Initializer list constructors

Smart pointers

Enum classes

Override and final specifiers

The noexcept specifier

Inline namespaces

Type aliases with using

User-defined literals

Alternate function style

Tuples

Constant expressions

The nullptr keyword

Variadic templates

Migrating to C++11

C++14 API features

The auto return type

The deprecated attribute

Variable templates

Const expression improvements

Binary literals and digit separators

Migrating to C++14

C++17 API features

Inline variables

String views

Optional

Any

Variant

Nested namespaces

Fold expressions

Checking for header availability

Byte type.

The maybe_unused attribute

Migrating to C++17

C++20 API features

Modules

Named Modules

Header units

The spaceship operator

Constraints and concepts

Abbreviated function templates

The consteval specifier

The constinit specifier

Migrating to C++20

C++23 API features

Expected values

Multidimensional subscript operator

Preprocessor directives

Migrating to C++23

8 - Performance

Pass input arguments by const reference

Minimize #include dependencies

Avoid "Winnebago" headers

Forward declarations

Redundant #include guards

Declaring constants

The constexpr, consteval, and constinit keywords

Initialization lists

Memory optimization

Don't inline functions until you need to

Copy on write

Iterating over elements

Iterators

Random access

Array references

Extern templates

Performance analysis

Time-based analysis

Memory-based analysis

Multithreading analysis

9 - Concurrency

Multithreading with C++

Terminology

Data races and race conditions

Thread safety

Reentrancy

Asynchronous tasks

Parallelism

Accessing shared data

Stateless APIs

Initializing shared data

Synchronized data access

Concurrent API design

Concurrency best practices

Thread-Safe Interface pattern

10 - Versioning

Version numbers

Version number significance

Esoteric numbering schemes

Creating a version API

Software branching strategies

Branching strategies

Branching policies

APIs and parallel branches

File formats and parallel products

Life cycle of an API

Levels of compatibility

Backward compatibility

Functional compatibility

Source compatibility

Binary/application binary interface compatibility

Binary incompatible API changes

Binary compatible API changes

Forward compatibility.

How to maintain backward compatibility

Adding functionality

Changing functionality

Deprecating functionality

Removing functionality

Inline namespaces for versioning

API reviews

The purpose of API reviews

Prerelease API reviews

Precommit API reviews

11 - Documentation

Reasons to write documentation

Defining behavior

Documenting the interface's contract

Communicating behavioral changes

What to document

Types of documentation

Automated API documentation

Overview documentation

Examples and tutorials

Release notes

License information

Documentation usability

Inclusive language

Using Doxygen

The configuration file

Comment style and commands

API comments

File comments

Class comments

Method comments

Enum comments

Sample header with documentation

12 - Testing

Reasons to write tests

Types of API testing

Unit testing

Integration testing

Performance testing

Writing good tests

Qualities of a good test

What to test

Focusing the testing effort

Working with quality assurance

Writing testable code

Test-driven development

Stub and mock objects

Testing private code

Using assertions

Contract programming

Record and playback functionality

Supporting internationalization

Automated testing tools

Test harnesses

Code coverage

Bug tracking

Continuous build system

13 - Objective-C and Swift

Interface design in C++ and Objective-C

Data hiding in Objective-C

Objective-C behind a C++ API

C++ behind an Objective-C API

C++ behind a Swift API

14 - Scripting

Adding script bindings

Extending versus embedding

Advantages of scripting

Language compatibility issues

Crossing the language barrier

Script binding technologies

Boost Python

Simplified wrapper and interface generator.

Python-SIP.

Notes:

Description based on publisher supplied metadata and other sources.

ISBN:

0-443-22220-7

OCLC:

1443195551