講義課件教程講稿api design for c

1、API Design for C+API Design for C+Martin ReddyAMSTERDAM BOSTON HEIDELBERG LONDON NEW YORK OXFORD PARIS SAN DIEGOSAN FRSCO SINGAPORE SYDNEY TOKYOMorgan Kaufmann Publishers is an imprint of ElsevierAcquiring Editor: Todd Green Editorial Assistant: Robyn Day Project Manager: Andre Cuello Designer: Eric

2、 DeCiccoMorgan Kaufmann is an imprint of Elsevier30 Corporate Drive, Suite 400, Burlington, MA 01803, USA# 2011 Elsevier, Inc.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 stor

3、age and retrieval system,without permission in writing from the publisher.s on how to seek permission, furtherinformation about the Publishers permissions policies and our arrangements with organizations such as the Copyright Clearance Center and the Copyright Licensing Agency, can be found at ourwe

4、bsite:.This book and the individual contributions contained in it are protected under copyright by the Publisher (other than as may be noted herein).NoticesKnowledge and best practice in this field are constantly changing. As new research and experience broaden our understanding, changes in research

5、 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 s

6、afety 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 forany injury and/or damage tos or property as a matter of products liability, negligence or oth

7、erwise, or fromany use or operation of any methods, products, instructions, or ideas contained in the material herein.Library of Congress Cataloging-in-Publication DataApplication submittedBritish Library Cataloguing-in-Publication DataA catalogue record for this book is available from the British L

8、ibrary.ISBN: 978 0 12 385003 4Printed in the United States of America 11 124 3 2 1For information on all MK publications visit our website atForewordI 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 re

9、searcher in the areas of computer graphicsand geometric m Studios.ing. It was in this line of work that I first met Martin at Pixar AnimationAs a graphics researcher I was accustomed to writing mathematically sophisticated papers. I was also formally trained as a computer scientist at a major univer

10、sity and had written my share of code.Armed with this background, when I was presented with the opportuto lead a group of softwareengineers working on a new generation of animation software for Pixar, I figured that it couldnt be any more difficult than research. After all, research is, by definitio

11、n, 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

12、, I eventually gave up and went back to graphics research.I cant 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 th

13、e 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 vo

14、ice 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 br

15、anching methodologies.In short, this book should be of great value to those creating or managing software activities. It isa compensive collection of best practices that have proven themselves time and time again.Tony DeRose Senior Scientist and Research Group Lead, Pixar Animation StudiosxvPrefaceW

16、riting 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 Program design.Interface (API

17、)An API presents a logical interface to a software component and hides the internalsrequired 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 h

18、ighly 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 comput

19、ing, and service-oriented architecture all imply the need for strong API design skills.Some popular C and C+ APIs that you may aly be aware of include the Standard TemplateLibrary (STL), Boost, the Microsoft Windows API (Win32), Microsoft Foundation Classes (MFC), libtiff, libpng, zlib, libxml+, Ope

20、nGL, MySQL+, Trolltechs Qt, wxWidgets, GTK+, KDE, Sky-peKit, POSIX pths, Intels Thing Building Blocks, the Netscape Plugin API, and theApache module API. In addition, many of Googles open-source projects are C+, as is much of the code on the , , and Web sites.APIs such as these are used

21、 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 an

22、d 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 requirem

23、ents, feature requests, and bug fixes cause software to evolve in waysthat were neveripated when it was first devised. However, changes to an API that is sharedby hundreds of end-user applications can cause major upheaval and ultimately may causesto abandon an API. The primary goal of good API desig

24、n is therefore to provide yours with thefunctionality they need while also causing minimal impact to their codeideally zero impact when you release a new version.WHY YOU SHOULDTHIS BOOKIf you write C+ code that another engineer relies upon, youre an API designer and this book has been written for yo

25、u.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 changecan

26、be integrated transparently and effortlessly intoapplications when they adopt the newxviixviiiPrefaceAPI 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 essentia

27、l 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 app

28、lications (Henning, 2009). Despite this fact, no other books currently on the market concentrate on the topic of API design for C+.Its worth noting that this book is not meant to be a general C+ programguide there arealy many good examples of these on the market. I will certainly cover lots of objec

29、t-orienteddesign 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 thequestion of how to implement the codethese interfaces, such as specific algorithm choicesor best p

30、ractices limited to the code within the curly braces of your function bodies.However, this book will cover the full bth of API development, from initial design throughimplementation, testing, documentation, release, versioning, maintenance, and deprecation. I will even cover specialized API topics s

31、uch 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 rat

32、her 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 syste

33、m APIs that have been usedto make Academy Award-winning movies, and open-source/server APIs that have been used bymillions 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 practica

34、l distillation of the techniques and strategies of industrial-strength API design that have been drawn from a range of real- world experiences.WHO IS THE TARGET AUDIENCEWhile this book is not a beginners guide to C+, I haveevery effort to make the text easy toand to explain all terminology and jargo

35、n clearly. The book should therefore be valuable to new programmers who have grasped the fundamentals of C+ and want to advance their design skills, as well as senior engineers and software architects who are seeking to gain new expertise to comple- ment their existing talents.There are three specif

36、ic groups ofers that I have borne in mind while writing this book.1. Practicing software engineers and architects. Junior and senior developers who are working on a specific API project and need pragmatic advice on how to produce the most elegant and enduring design.2. Technical managers. Program an

37、d product managers who are responsible for producing an API product and who want to gain greater insight into the technical issues and development processes of API design.Prefacexix3.s and educators. Computer science and software engineerings who are learninghow to program and are seeking a thorough

38、 resource on software design that is informed by prac- tical experience on large-scale projects.FOCUSING ON C+While there are many generic API design methodologies that can be taught skills that apply equallywell to any program ticular programlanguage or environment ultimately an API has to be expre

39、ssed in a par- language. It is therefore important to understand the language-specific featuresthat 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 alllanguages. W

40、hileers who wish to develop APIs for other languages, such as Java or C#, maystill gain much general insight from this text, the book is directly targeted at C+ engineers who must write and maintain APIs for other engineers to consume.C+ is still one of the most widely used programlanguages for larg

41、e software projects andtends to be the most popular choice for performance-critical code. As a result, there are many diverse 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 inc

42、lude copious source code examples to illustrate these concepts better. This means that I will deal with C+-specific topics such as templates, encapsulation, inheritance, namespaces, operators, const correctness, memory management, use of STL, the pimpl idiom, and so on.Additionally, this book will b

43、e published during an exciting time in the evolution of C+. A new 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

44、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. This version is referred to informally as C+0x, until such time that the standard is rati-fied and the date of publication is known.

45、By the time youthis book, the new standard willlikely 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. I

46、n fact, some of the major C+compilers have aly started to implement many of the proposed new features. In terms of APIdesign, several of these new language features can be used to produce more elegant and sturdy inter- faces. As such, I have endeavored to highlight and explain those areas of C+0x th

47、roughout the book. This book should therefore remain a relevant resource for several years to come.CONVENTIONSWhile it is more traditional to employ the term “user” to mean awho uses a software appli-cation, such as a user of Microsoft Word or Mozilla Firefox, in the context of API design I will app

48、ly the term to mean a software developer who is creating an application and is using an API to achievexxPrefacethis. In other words, I will generally be talking about API users and not application users. The term“” will be used synonymously in this regard. Note that the term “,” in addition to refer

49、ringto a human user of your API, can also refer im functions in your API.ally to other pieces of software that must callWhile there are many file format extensions used to identify C+ source and header files, such as.cpp, .cc, .cxx, .h, .hh, and .hpp, I will standardize on the use of .cpp and .h thr

50、oughout this book. “I will also use the terms module and component” interchangeably to mean a single .cpp and .h file pair. These are notably not equivalent to a class because a component or module may contain multi- ple classes. I will use the term library to refer to a physical collection, or pack

51、age, of components, that is, library module/component class.The term method, while generally understood in the object-oriented programcommu, isnot strictly a C+ term; it originally evolved from the Smalltalk language. The equivalent C+ term is member function, although some engineers prefer the more

52、 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 va

53、riable 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 presen

54、t, 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

55、, for example, sStaticVar.It should be pointed out that the source examples within the book are often only code snippets and are not meant to show fully functional samples. I will also often strip comments from the exam- ple code in the book. This is done for reasons of brevity and clarity. In parti

56、cular, I will often omitany preprocessor guard statements around a header file. I will assume that theer is aware thatevery C/C+ header should enall of its content within guard statements and that its good prac-tice to contain all of your API declarations within a consistent namespace (as covered in

57、 Chapters 3 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.#ifndef MY MODULE H #define MY MODULE H/ required #include files. .namespace apibook / API declarations . .#endifPrefacexxiBOOK WEB SITEThis book al

58、so has a supporting Web site,. On this site you can find generalinformation about the book, as well as supporting material, such as the complete set of source codeexamples contained within the text. Feelto download and play with these samples yourselfthey were designed to be as simple as possible, while still being useful and illustrative. I have used the cross-platform CMake build system t