Acquiring Editor: Todd Green Editorial Assistant: Robyn Day Project Manager: Andre´ Cuello Designer: Eric DeCicco Morgan Kaufmann is an imprint of Elsevier 30 Corporate Drive, Suite 400, Burlington, MA 01803, USA # 2011 Elsevier, Inc. All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or any information storage and retrieval system, without permission in writing from the publisher. Details on how to seek permission, further information about the Publisher’s permissions policies and our arrangements with organizations such as the Copyright Clearance Center and the Copyright Licensing Agency, can be found at our website: www.elsevier.com/permissions. This book and the individual contributions contained in it are protected under copyright by the Publisher (other than as may be noted herein). Notices Knowledge and best practice in this field are constantly changing. As new research and experience broaden our understanding, changes in research methods or professional practices may become necessary. Practitioners and researchers must always rely on their own experience and knowledge in evaluating and using any information or methods described herein. In using such information or methods they should be mindful of their own safety and the safety of others, including parties for whom they have a professional responsibility. To the fullest extent of the law, neither the Publisher nor the authors, contributors, or editors, assume any liability for any injury and/or damage to persons or property as a matter of products liability, negligence or otherwise, or from any use or operation of any methods, products, instructions, or ideas contained in the material herein. Library of Congress Cataloging-in-Publication Data Application submitted British Library Cataloguing-in-Publication Data A catalogue record for this book is available from the British Library. ISBN: 978 0 12 385003 4 Printed in the United States of America 1112131410987654321 For information on all MK publications visit our website at www.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. As a graphics researcher I was accustomed to writing mathematically sophisticated papers. I was also formally trained as a computer scientist at a major university and had written my share of code. Armed with this background, when I was presented with the opportunity to lead a group of software engineers working on a new generation of animation software for Pixar, I figured that it couldn’t be 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 I had ever been presented with. After more years than I care to admit, I eventually gave up and went 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), but from the perspec- tive of an in-the-trenches software engineer and manager. He has experienced firsthand the importance of good software design and has emerged as an articulate voice of what “good” means. In this book he presents effective strategies for achieving that goal. 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. In short, this book should be of great value to those creating or managing software activities. It is 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 Writing large applications in C++ is a complex and tricky business. However, designing reusable C++ interfaces that are robust, stable, easy to use, and durable is even more difficult. The best way to suc- 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. Modern software development has become highly dependent on APIs, from low-level application 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. Some popular C and C++ APIs that you may already be aware of include the Standard Template Library (STL), Boost, the Microsoft Windows API (Win32), Microsoft Foundation Classes (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++,asismuchof thecodeonthesourceforge.net, bitbucket.org,andfreshmeat.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 to abandon an API. The primary goal of good API design is therefore to provide your clients with the functionality they need while also causing minimal impact to their code ideally zero impact when you release a new version. 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. Interfaces are the most important code that you write because a problem with your interface is far more costly to fix than a bug in your implementation. For instance, an interface change may require 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 API version. Put in more economic terms, a poorly designed interface can seriously reduce the long- 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. In terms of my own credentials to write this book, I have led the development of APIs for research code shared by several collaborating institutions, in-house animation system APIs that have been used to make Academy Award-winning movies, and open-source client/server APIs that have been used by millions of people worldwide. Throughout all of these disparate experiences, I have consistently wit- nessed the need for high-quality API design. This book therefore presents a practical distillation of the techniques and strategies of industrial-strength API design that have been drawn from a range of real- world experiences.