• Increase font size
  • Default font size
  • Decrease font size


  Thursday, September 9th, 2010

There are many tools out there that will create API documentation automatically from the comments in your code. Doxygen is one that I have used a lot and also like a lot. It can extract documentation from many different languages, including C and C++, it works on Windows, Mac OS X, and Linux, and it has a huge degree of configurability. It’s also open source. Check it out for your API reference documentation needs.

Non-functional Testing

  Thursday, September 9th, 2010

Most testing efforts are targeted toward testing the actual functionality of an API, i.e., what it is supposed to do. However, there is another class of testing called non-functional testing. This involves testing the quality of the software from the user’s perspective. It can involve things like performance testing, scalability testing, and security testing. The following article gives a comparison between functional and non-functional testing.

Unit Testing Frameworks

  Thursday, September 9th, 2010

A unit test is a white-box testing technique that a developer performs. White-box means that you write the tests with knowledge of the implementation of the API. There are many frameworks out there that help you write, maintain, and run unit tests for your code. Most of these are based upon the J-Unit style of unit testing. Wikipedia offers a good categorization of unit test frameworks that are available for C and C++. See:

API Testing

  Thursday, September 9th, 2010

This article provides a QA engineer’s perspective on API testing. It pulls out some of different types of testing approaches, such as unit testing and black-box testing, and provides some guidance on writing API tests.

Note that the term “API Testing” is commonly used in the QA domain to mean programmatic black-box tests that a QA engineer writes.  However, I view the topic of “testing an API” as being wider than this, encompassing unit testing, integration testing, and non-functional testing, and performed by either developers or QA engineers.

Qt API Design Notes

  Thursday, September 9th, 2010

The Nokia Qt library provides a cross-platform application and UI framework for C++. It is often used to create user interfaces for programs that must run on several different platforms, but it also includes a large array of lower-level functionality, such as classes to handle threads, database access, regular expressions, networks, and XML.

Several of the Qt developers have written on the topic of good API design for C++. For example, Matthias Ettrich wrote an article on designing Qt-style C++ APIs that covers many good issues such as characteristics of good APIs, the boolean parameter trap, and the art of naming. See:

Also, Jasmin Blanchette wrote a document called “The Little Manual of API Design” that provides a similar treatment but with a bit more detail and covers more material on the design process and design guidelines. See:

Java API Design

  Thursday, September 9th, 2010

Jaroslav Tulach wrote the book “Practical API Design: Confessions of a Java Framework Architect.” Jaroslav also maintains a website to support the book. This site includes lots of tips on API design that, while focused on Java, still offer general insights for C++ engineers working on API tasks. His site also provides a Java source code download for many of the examples in his book.

You can also read a review of Tulach’s book here:

Symbian’s API Change Control Process

  Wednesday, September 8th, 2010

The Symbian Developer wiki defines a process for public API changes to the Symbian platform. This involves a submitting a Change Request (CR) to an Architecture Council for approval before code is integrated. The main principles of their API development process are:

  • Public APIs must remain backwards compatible during their lifetime.
  • Public APIs can be extended with non-disruptive changes.
  • Public APIs must go through a deprecation period before removal.

For details, see:

The API process is illustrated with the following figure:

KDE’s Binary Compatibility Policy

  Wednesday, September 8th, 2010

The KDE Project offers some guidance on the difference between source and binary compatibility, and provides a great list of Do’s and Don’ts if you want to maintain binary compatibility for an API.

This document defines binary and source compatibility as:

A library is binary compatible, if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn’t require any further modifications, the library is source compatible.


An Application Programming Interface (API) provides a logical interface to a piece of software and hides its internal details. This website is dedicated to a book on designing APIs for C++ and includes articles and links on API development.


The book is accompanied by a source code package that contains many of the examples in the text. Download it for free.


Dr. Reddy has also published a computer graphics book called Level of Detail for 3D Graphics. Check it out too!.
Copyright (c) 2024 Martin Reddy. All rights reserved. Login