API Design for C++

446 Pages·2011·6.4 MB·English

by  Martin Reddy

++
API Design for C
++
API Design for C
Martin Reddy
AMSTERDAM (cid:129) BOSTON (cid:129) HEIDELBERG (cid:129) LONDON
NEW YORK (cid:129) OXFORD (cid:129) PARIS (cid:129) SAN DIEGO
SAN FRANCISCO (cid:129) SINGAPORE (cid:129) SYDNEY (cid:129) TOKYO
Morgan Kaufmann Publishers is an imprint of Elsevier
AcquiringEditor:ToddGreen
EditorialAssistant:RobynDay
ProjectManager:Andre´ Cuello
Designer:EricDeCicco
MorganKaufmannisanimprintofElsevier
30CorporateDrive,Suite400,Burlington,MA01803,USA
#2011Elsevier,Inc.Allrightsreserved.
Nopartofthispublicationmaybereproducedortransmittedinanyformorbyanymeans,electronic
ormechanical,includingphotocopying,recording,oranyinformationstorageandretrievalsystem,
withoutpermissioninwritingfromthepublisher.Detailsonhowtoseekpermission,further
informationaboutthePublisher’spermissionspoliciesandourarrangementswithorganizationssuch
astheCopyrightClearanceCenterandtheCopyrightLicensingAgency,canbefoundatour
website:www.elsevier.com/permissions.
Thisbookandtheindividualcontributionscontainedinitareprotectedundercopyrightbythe
Publisher(otherthanasmaybenotedherein).
Notices
Knowledgeandbestpracticeinthisfieldareconstantlychanging.Asnewresearchandexperiencebroaden
ourunderstanding,changesinresearchmethodsorprofessionalpracticesmaybecomenecessary.Practitioners
andresearchersmustalwaysrelyontheirownexperienceandknowledgeinevaluatingandusingany
informationormethodsdescribedherein.Inusingsuchinformationormethodstheyshouldbemindfuloftheir
ownsafetyandthesafetyofothers,includingpartiesforwhomtheyhaveaprofessionalresponsibility.
Tothefullestextentofthelaw,neitherthePublishernortheauthors,contributors,oreditors,assumeanyliabilityfor
anyinjuryand/ordamagetopersonsorpropertyasamatterofproductsliability,negligenceorotherwise,orfrom
anyuseoroperationofanymethods,products,instructions,orideascontainedinthematerialherein.
LibraryofCongressCataloging-in-PublicationData
Applicationsubmitted
BritishLibraryCataloguing-in-PublicationData
AcataloguerecordforthisbookisavailablefromtheBritishLibrary.
ISBN: 978-0-12-385003-4
PrintedintheUnitedStatesofAmerica
11 12 13 14 10 9 8 7 6 5 4 3 2 1
ForinformationonallMKpublicationsvisitourwebsiteatwww.mkp.com
Foreword
I should begin by confessing that I do not consider myself a world-class API designer or software
engineer. I do, however, consider myself an expert researcher in the areas of computer graphics
and geometric modeling. It was in this line of work that I first met Martin at Pixar Animation
Studios.
AsagraphicsresearcherIwasaccustomedtowritingmathematicallysophisticatedpapers.Iwas
alsoformallytrainedasacomputerscientistatamajoruniversityandhadwrittenmyshareofcode.
Armedwiththisbackground,whenIwaspresentedwiththeopportunitytoleadagroupofsoftware
engineersworking ona newgenerationofanimationsoftware for Pixar, Ifigured that itcouldn’tbe
any more difficult than research. After all, research is, by definition, the creation of the unknown,
whereas engineering is the implementation of well-understood subjects. I could not have been more
wrong.
I came to realize that software engineering was, without a doubt, the most difficult challenge
Ihadeverbeenpresentedwith.AftermoreyearsthanIcaretoadmit,Ieventuallygaveupandwent
back to graphics research.
I can’t tell you how much I would have benefitted from a book such as “API Design for C++.”
Many of the lessons we learned the hard way have been captured by Martin in this insightful,
easy-to-use book. Martin approaches the subject not from the perspective of an academic software
researcher (although he draws heavily from results and insights gained there), butfromtheperspec-
tiveofanin-the-trenchessoftwareengineerandmanager.Hehasexperiencedfirsthandtheimportance
of good software design and hasemerged as an articulate voice of what “good” means. In this book
hepresentseffectivestrategiesforachievingthatgoal.
I particularly like that Martin is not focusing just on API design, but more broadly on software
life cycles, allowing him to cover topics such as versioning, strategies for backward compatibility,
and branching methodologies.
Inshort,thisbookshouldbeofgreatvaluetothosecreatingormanagingsoftwareactivities.Itis
a comprehensive collection of best practices that have proven themselves time and time again.
Tony DeRose
Senior Scientist and Research Group Lead, Pixar Animation Studios
xv
Preface
WritinglargeapplicationsinC++isacomplexandtrickybusiness.However,designingreusableC++
interfacesthatarerobust,stable,easytouse,anddurableisevenmoredifficult.Thebestwaytosuc-
ceed in this endeavor is to adhere to the tenets of good Application Programming Interface (API)
design.
An API presents a logical interface to a software component and hides the internal details
required to implement that component. It offers a high-level abstraction for a module and promotes
code reuse by allowing multiple applications to share the same functionality.
ModernsoftwaredevelopmenthasbecomehighlydependentonAPIs,fromlow-levelapplication
frameworks to data format APIs and graphical user interface (GUI) frameworks. In fact, common
software engineering terms such as modular development, code reuse, componentization, dynamic
link library or DLL, software frameworks, distributed computing, and service-oriented architecture
all imply the need for strong API design skills.
SomepopularCandC++APIsthatyoumayalreadybeawareofincludetheStandardTemplate
Library(STL),Boost,theMicrosoftWindowsAPI(Win32),MicrosoftFoundationClasses(MFC),
libtiff, libpng, zlib, libxml++, OpenGL, MySQL++, Trolltech’s Qt, wxWidgets, GTK+, KDE, Sky-
peKit, POSIX pthreads, Intel’s Threading Building Blocks, the Netscape Plugin API, and the
Apache module API. In addition, many of Google’s open-source projects are C++, as is much of
the code on the sourceforge.net, bitbucket.org, and freshmeat.net Web sites.
APIs such as these are used in all facets of software development, from desktop applications, to
mobile computing and embedded systems, to Web development. For example, the Mozilla Firefox
Web browser is built on top of more than 80 dynamic libraries, each of which provides the imple-
mentation for one or more APIs.
Elegant and robust API design is therefore a critical aspect of contemporary software develop-
ment. One important way in which this differs from standard application development is the far
greater need for change management. As we all know, change is an inevitable factor in software
development; new requirements, feature requests, and bug fixes cause software to evolve in ways
that were never anticipated when it was first devised. However, changes to an API that is shared
by hundreds of end-user applications can cause major upheaval and ultimately may cause clients
toabandonanAPI.TheprimarygoalofgoodAPIdesignisthereforetoprovideyourclientswiththe
functionalitytheyneedwhilealsocausingminimalimpacttotheircode—ideallyzeroimpact—when
youreleaseanewversion.
WHY YOU SHOULD READ THIS BOOK
If you write C++ code that another engineer relies upon, you’re an API designer and this book has
been written for you.
Interfacesarethemostimportantcodethatyouwritebecauseaproblemwithyourinterfaceisfar
morecostly tofixthanabuginyourimplementation.Forinstance,aninterface changemayrequire
all of the applications based on your code to be updated, whereas an implementation-only change
can be integrated transparently and effortlessly into client applications when they adopt the new
xvii
xviii Preface
APIversion.Putinmoreeconomicterms,apoorlydesignedinterfacecanseriouslyreducethelong-
term survival of your code. Learning how to create high-quality interfaces is therefore an essential
engineering skill, and the central focus of this book.
As Michi Henning noted, API design is more important today than it was 20 years ago. This is
because many more APIs have been designed in recent years. These also provide richer and more
complex functionality and are shared by more end-user applications (Henning, 2009). Despite this
fact, no other books currently on the market concentrate on the topic of API design for C++.
It’s worth noting that this book is not meant to be a general C++ programming guide—there are
already many good examples of these on the market. I will certainly cover lots of object-oriented
design material and present many handy C++ tips and tricks. However, I will focus on techniques
for representing clean modular interfaces in C++. By corollary, I will not dive as deeply into the
question of how to implement the code behind these interfaces, such as specific algorithm choices
or best practices limited to the code within the curly braces of your function bodies.
However, this book will cover the full breadth of API development, from initial design through
implementation, testing, documentation, release, versioning, maintenance, and deprecation. I will
even cover specialized API topics such as creating scripting and plugin APIs. While many of these
topics are also relevant to software development in general, the focus here will be on the particular
implications for API design. For example, when discussing testing strategies I will concentrate on
automated API testing techniques rather than attempting to include end-user application testing
techniques such as GUI testing, system testing, or manual testing.
Intermsofmyowncredentialstowritethisbook,IhaveledthedevelopmentofAPIsforresearch
codesharedbyseveralcollaboratinginstitutions,in-houseanimationsystemAPIsthathavebeenused
tomakeAcademyAward-winningmovies,andopen-sourceclient/serverAPIsthathavebeenusedby
millionsofpeopleworldwide.Throughoutallofthesedisparateexperiences,Ihaveconsistentlywit-
nessedtheneedforhigh-qualityAPIdesign.Thisbookthereforepresentsapracticaldistillationofthe
techniquesandstrategiesofindustrial-strengthAPIdesignthathavebeendrawnfromarangeofreal-
worldexperiences.
WHO IS THE TARGET AUDIENCE
While this book is not a beginner’s guide to C++, I have made every effort to make the text easy to
readandtoexplainallterminologyandjargonclearly.Thebookshouldthereforebevaluabletonew
programmers who have grasped the fundamentals of C++and want toadvancetheir designskills,as
well as senior engineers and software architects who are seeking to gain new expertise to comple-
ment their existing talents.
There are three specific groups of readers that I have borne in mind while writing this book.
1. Practicingsoftwareengineersandarchitects.Juniorandseniordeveloperswhoareworkingon
a specific API project and need pragmatic advice on how to produce the most elegant and
enduring design.
2. Technicalmanagers. Program and product managers who are responsible for producing anAPI
productandwhowanttogaingreaterinsightintothetechnicalissuesanddevelopmentprocesses
of API design.
Preface xix
3. Students and educators. Computer science and software engineering students who are learning
howtoprogramandareseekingathoroughresourceonsoftwaredesignthatisinformedbyprac-
tical experience on large-scale projects.
FOCUSING ON C++
WhiletherearemanygenericAPIdesignmethodologiesthatcanbetaught—skillsthatapplyequally
welltoanyprogramminglanguageorenvironment—ultimatelyanAPIhastobeexpressedinapar-
ticular programming language. It is therefore important to understand the language-specific features
that contribute to exemplary API design. This book is therefore focused on the issues of designing
APIs for a single language (C++) rather than diluting the content to make it applicable for all
languages. While readers who wish to develop APIs for other languages, such as Java or C#, may
stillgainmuchgeneralinsightfromthistext,thebookisdirectlytargetedatC++engineerswhomust
write and maintain APIs for other engineers to consume.
C++ is still one of the most widely used programming languages for large software projects and
tendstobethemostpopularchoiceforperformance-criticalcode.Asaresult,therearemanydiverse
C and C++ APIs available for you to use in your own applications (some of which I listed earlier).
I will therefore concentrate on aspects of producing good APIs in C++ and include copious source
codeexamplestoillustratetheseconceptsbetter.ThismeansthatIwilldealwithC++-specifictopics
such as templates, encapsulation, inheritance, namespaces, operators, const correctness, memory
management, use of STL, the pimpl idiom, and so on.
Additionally,thisbookwillbepublishedduringanexciting timeintheevolutionofC++.Anew
version of the C++ specification is currently working its way through the ISO/IEC standardization
process. Most C++ compilers currently aim to conform to the standard that was first published in
1998, known as C++98. A later revision of this standard was published in 2003 to correct several
defects. Since that time, the standards committee has been working on a major new version of the
specification.ThisversionisreferredtoinformallyasC++0x,untilsuchtimethatthestandardisrati-
fied and the date of publication is known. By the time you read this book, the new standard will
likely have been published. However, at the time of writing, it is still referred to as C++0x.
Nonetheless, C++0x has reached an advanced stage of the standardization process, and many of
the new features can be predicted with relatively high confidence. In fact, some of the major C++
compilers have already started to implement many of the proposed new features. In terms of API
design,severalofthesenewlanguagefeaturescanbeusedtoproducemoreelegantandsturdyinter-
faces.Assuch,IhaveendeavoredtohighlightandexplainthoseareasofC++0xthroughoutthebook.
This book should therefore remain a relevant resource for several years to come.
CONVENTIONS
While it is more traditional to employ the term “user” to mean a person who uses a software appli-
cation,suchasauserofMicrosoftWordorMozillaFirefox,inthecontextofAPIdesignIwillapply
thetermtomeanasoftwaredeveloperwhoiscreatinganapplicationandisusinganAPItoachieve
xx Preface
this. In other words, I will generally be talking about API users and not application users. The term
“client”willbeusedsynonymouslyinthisregard.Notethattheterm“client,”inadditiontoreferring
to a human user of your API, can also refer impersonally to other pieces of software that must call
functions in your API.
WhiletherearemanyfileformatextensionsusedtoidentifyC++sourceandheaderfiles,suchas
.cpp,.cc,.cxx,.h,.hh,and.hpp,Iwillstandardizeontheuseof.cppand.hthroughoutthisbook.
“Iwillalsousethetermsmoduleandcomponent”interchangeablytomeanasingle.cppand.hfile
pair.Thesearenotablynotequivalenttoaclassbecauseacomponentormodulemaycontainmulti-
ple classes. I will use the term library to refer to a physical collection, or package, of components,
that is, library > module/component > class.
Thetermmethod,whilegenerallyunderstoodintheobject-orientedprogrammingcommunity,is
notstrictlyaC++term;itoriginallyevolvedfromtheSmalltalklanguage.TheequivalentC++termis
member function, although some engineers prefer the more specific definition of virtual member
function. Because I am not particularly concerned with the subtleties of these terms in this book, I
will use method and member function interchangeably. Similarly, although the term data member
is the more correct C++ expression, I will treat the term member variable as a synonym.
In terms of typographical conventions, I will use a fixed-width font to typeset all source code
examples, as well as any filenames or language keywords that may appear in the text. Also, I will
prefer upper camel case for all class and function names in the examples that I present, that is,
CamelCase instead of camelCase or snake_case, although obviously I will preserve the case for
any external code that I reference, such as std::for_each(). I follow the convention of using an
“m” prefix in front of data members, for example, mMemberVar, and “s” in front of static variables,
for example, sStaticVar.
It should be pointed out that the source examples within the book are often only code snippets
andarenotmeanttoshowfullyfunctionalsamples.Iwillalsooftenstripcommentsfromtheexam-
ple code in the book. This is done for reasons of brevity and clarity. In particular, I will often omit
any preprocessor guard statements around a header file. I will assume that the reader is aware that
everyC/C++headershouldencloseallofitscontentwithinguardstatementsandthatit’sgoodprac-
tice tocontain allof yourAPI declarationswithin aconsistent namespace(as coveredinChapters3
and 6). In other words, it should be assumed that each header file that I present is implicitly sur-
rounded by code, such as the following.
#ifndefMY_MODULE_H
#defineMY_MODULE_H
//required#includefiles...
namespaceapibook{
//APIdeclarations...
}
#endif
Preface xxi
TIP
IwillalsohighlightvariousAPIdesigntipsandkeyconceptsthroughoutthebook.Thesecalloutsareprovidedto
letyousearchquicklyforaconceptyouwishtoreread.Ifyouareparticularlypressedfortime,youcouldsimply
scanthebookforthesetipsandthenreadthesurroundingtexttogaingreaterinsightforthosetopicsthatinterest
youthemost.
BOOK WEB SITE
This book also has a supporting Web site, http://APIBook.com/. On this site you can find general
information about the book, as well as supporting material, such as the complete set of source code
examples contained within the text. Feel free to download and play with these samples yourself—
they were designed to be as simple as possible, while still being useful and illustrative. I have used
the cross-platform CMake build system to facilitate compiling and linking the examples so they
should work on Windows, Mac OS X, and UNIX operating systems.
I will also publish any information about new revisions of this book and any errata on this Web
site,aswellasusefullinkstootherrelatedAPIresourcesontheInternet,suchasinterestingtoolkits,
articles, and utilities.
The book Web site also provides access to a utility that I wrote called API Diff. This program
lets you compare two versions of an API and review differences to code or comments in a visual
side-by-sideformat.Youcanalsogenerateareportofeverythingthatchangedinaparticularrelease
so that your clients know exactly what to look out for. This utility is available for Windows, Mac
OS X, and Linux.