When developing in C++, an impeccable API is a must have: it has to be as simple as possible, abstract, generic, and extensible. One important generic concept that STL made C++ developers familiar with is the concept of iterator.

An iterator is used to visit the elements of a container without exposing how the container is implemented (e.g., a vector, a list, a red-black tree, a hash set, a queue, etc). Iterators are central to generic programming because they are an interface between containers and applications. Applications need access to the elements of containers, but they usually do not need to know how elements are stored in containers. Iterators make possible to write generic algorithms that operate on different kinds of containers.

For example, the following code snippet exposes the nature of the container –a vector.

     void process(const std::vector<E>& v)
     {
         for (unsigned i = 0; i < v.size(); ++i) {
             process(v[i]);
         }
     }

If we want to have the same function operating on a list, we have to write a separate function. Or if we later decide that a list or a hash set is more appropriate as a container, we need to rewrite the code everywhere we access the vector. This may require a lot of changes in many files. Contrast this container-specific visitation scheme to the following:

     template <typename Container>
     void process(const Container& c)
     {
         typename Container::const_iterator itr = c.begin();
         typename Container::const_iterator end = c.end();
         for (; itr != end; ++itr) {
             process(*itr);
         }
     }

Using the notion of iterator, we have a generic processing of a container ‘c’, whether it is a vector, a list, a hash set, or any data structure that provides iterators in its API. Even better, we can write a generic process function that only takes an iterator range, without assuming that the container has a begin() and end() method:

     template <typename Iterator>
     void process(Iterator begin, Iterator end)
     {
         for (; itr != end; ++itr) {
             process(*itr);
         }
     }

An STL iterator is a commodity that behaves as a scalar type:

• It can be allocated on the heap
• It can be copied
• It can be passed by value
• It can be assigned to

The essence of an iterator is captured by the following API.

     template <typename T>
     class Itr {
     public:
         Itr();
         ~Itr();
         Itr(const Itr& o);                   // Copy constructor
         Itr& operator=(const Itr& o);        // Assignment operator
         Itr& operator++();                   // Next element
         T&   operator*();                    // Dereference
         bool operator==(const Itr& o) const; // Comparison
         bool operator!=(const Itr& o) const { return !(*this == o); }
     }

Usually the container will provide a begin() and end() method, which build the iterators that denote the container’s range. Writing these begin/end methods is an easy task if the container is derived from a STL container, if the container has a data member that is an STL container, or if the iterator is a scalar type, like a pointer or an index.

It is more complicated if we want iterators that dereference to the same type of object, but that must visit several containers, possibly of different types, or iterators that visit containers in different manners. For instance let us assume that we have objects with some property (say, a color) stored in several containers, some of them of different types. We would like to visit all the objects, independently of the number of containers and their type, or we would like to visit objects of a given color, or we would like to visit objects that satisfy some predicate:

     class E;

     Itr<E> begin(); // This give the range to visit
     Itr<E> end();   // all the elements of type E      

     Itr<E> begin(const Color& color); // Same as above but only for the
     Itr<E> end(const Coir& color);    // elements of the given color      

     class Predicate {
     public:
         bool operator()(const E& e);
     };      

     Itr<E> begin(Predicate& p); // Same as above but only for the
     Itr<E> end(Predicate& p);   // elements that satisfy the predicate

In this case the iterator is more complex than a scalar type like a pointer or an index: it needs to keep track of which container it is currently visiting, or which color or predicate it needs to check. In general, the iterator may have data members so that it can fulfill its task. Also we want to factorize the code and reuse general purpose iterators’ methods when writing more targeted iterators –e.g., visiting elements of a specific color should make use of the next-element method Itr<E>::operator++(). This can be done by having Itr<E> be a virtual class, and having derived classes to implement the different iterators. For example:

     class E {
     public:
         Color& color() const;
     };      

     template <typename E>
     class ColoredItr<E> : public Itr<E> {
     private:
         typedef Itr<E> _Super;
     public:
         ColoredItr<E>(const Color& color) : Itr<E>(), color_(color) {}
         virtual ~ColoredItr<E>;
         virtual ColoredItr<E>& Operator++() {
            for (; _Super::operator*().color() != color_; _Super::operator++());
            return *this;
         }
     private:
         Color color_;
    };

We would like a generic iterator that meets all the requirements described above:

• It can be allocated on the heap
• It can be copied
• It can be passed by value
• It can be assigned to
• It dereferences to the same type
• It can visit several containers
• It can visit containers of different types
• It can visit containers in arbitrary manners

This can be implemented as follows.

     template<typename E>
     class ItrBase {
     public:
         ItrBase() {}
         virtual ~ItrBase() {}
         virtual void  operator++() {}
         virtual E&    operator*() const { return E(); }
         virtual ItrBase* clone() const { return new ItrBase(*this); }
         // The == operator is non-virtual. It checks that the
         // derived objects have compatible types, then calls the
         // virtual comparison function equal.
         bool operator==(const ItrBase& o) const {
             return typeid(*this) == typeid(o) && equal(o);
         }
     protected:
         virtual bool equal(const ItrBase& o) const { return true; }
     };      

     template<typename E>
     class Itr {
     public:
         Itr() : itr_(0) {}
         ~Itr() { delete itr_; }
         Itr(const Itr& o) : itr_(o.itr_->clone()) {}
         Itr& operator=(const Itr& o) {
             if (itr_ != o.itr_) { delete itr_; itr_ = o.itr_->clone(); }
             return *this;
         }
         Itr&  operator++() { ++(*itr_); return *this; }
         E&    operator*() const { return *(*itr_); }
         bool  operator==(const Itr& o) const {
             return (itr_ == o.itr_) || (*itr_ == *o.itr_);
         }
         bool  operator!=(const Itr& o) const { return !(*this == o); }      

     protected:
         ItrBase<E>* itr_;
     };

The ItrBase class is the top class of the hierarchy. Itr is simply a wrapper on a pointer to an ItrBase, so that it can be allocated on the heap –the actual implementation of the class deriving from ItrBase can have an arbitrary size. Note how the Itr copy and assignment operators are implemented via the ItrBase::clone() method, so that Itr behaves as a scalar type. Last but not least, the (non-virtual) ItrBase::operator== equality operator first checks for type equality before calling the (virtual) equality method equal on the virtual subclass. The reason ItrBase is not a pure virtual is that it can conveniently be used to denote an empty range, i.e., the range (ItrBase(), ItrBase()) is empty.

Iterators on containers of elements of type E just need to derive from ItrBase<E>, and a factory providing the begin() and end() methods for any specialized iterator returns object of type Itr<E>.

For example, let us assume that we have a container c of E’s, and that we want an iterator to visit (1) all the elements of c, possibly with repetition; (2) all the elements of c without repetition. This can be done as follows.

    class E;

    class ItrAll : public ItrBase<E> {
    private:
        typedef ItrAll     _Self;
        typedef ItrBase<E> _Super;
    public:
        ItrAll(Container& c) : _Super(), c_(c) {}
        virtual ~ItrAll() {}
        virtual void  operator++() { ++itr_; }
        virtual E&    operator*() const { return *itr_; }
        virtual ItrBase<E>* clone() const { return new _Self(*this); }
    protected:
        virtual bool equal(const ItrBase<E>& o) const {
            // Casting is safe since types have been checked by _Super::operator==
            const _Self& o2 = static_cast<const _Self&>(o);
            return &c_ == &o2.c_ && itr_ == o2.itr_;
        }
    protected:
        Container&          c_;
        Container::iterator itr_;
    };     

    class ItrNoRepeat : public ItrAll {
    private:
        typedef ItrNoRepeat _Self;
        typedef ItrAll      _Super;
    public:
        ItrNoRepeat (Container& c) : _Super(c) {}
        virtual ~ItrNoRepeat () {}
        virtual void  operator++() {
            _Super::operator++(); // Go to the next element then
            // look for an element that has not been visited yet.
            for (; itr_ != c_.end(); _Super::operator++()) {
                E& e = _Super::operator*();
                if (visited_.find(e) == visited_.end()) {
                    visited_.insert(e);
                    return;
                }
            }
        }
        virtual E&    operator*() const { return _Super::operator*(); }
        virtual ItrBase<E>* clone() const { return new _Self(*this); }
    protected:
        virtual bool equal(const ItrBase<E>& o) const { return _Super::equal(o); }
    protected:
        set<E> visited_;
    };     

    // Build the container’s range w/ and w/o repetition
    Itr<E> begin(Container& c, bool noRepeat = false)
    {
        Itr<E> o;
        if (noRepeat) {
            o.itr_ = new ItrNoRepeat(c);
        } else {
            o.itr_ = new ItrAll(c);
        }
        o.itr_->itr_ = c.begin();
        return o;
    }     

    Itr<E> end(Container& c, bool noRepeat = false)
    {
        Itr<E> o;
        if (noRepeat) {
            o.itr_ = new ItrNoRepeat(c);
        } else {
            o.itr_ = new ItrAll(c);
        }
        o.itr_->itr_ = c.end();
        return o;
    }

Related posts:

1. API design 101

Continue reading Twitter sure is a rollercoaster, but going up or down?

Related posts:

1. What is Twitter’s next step?
2. The truth about Twitter usage
3. Is Twitter Flattening? A Short Answer

Getting actual figures about the size of the functional verification market proves to be elusive because of the way the products are tied to synthesis license deals, and because of the lack of independent analysts in EDA. Still, the simulation and emulation market of digital systems can be estimated to be at least five times larger than today’s formal verification market. But simulation can only take you so far, so one wonders why formal verification does not have a larger share. Is it because the technology is limited, or because the market is not ready?

Equivalence checking

Equivalence checking (EC) consists of verifying that a netlist implements the behavior specified by a RTL description, or that two netlists are equivalent. Historically, EC is the first industrial formal verification tool brought to the ASIC world. Cadence’s Conformal is still the reference (about 60% of the market), with Synopsys’ Formality coming second.

EC’s technology is very mature, but this does not mean no further progress is necessary. Flip-flop matching, the primarily step that consists of determining the pairs of flip-flops that need to be compared, is expected to be done quickly and automatically, with no manual guidance. Datapath verification remains a major challenge, and proving the correctness of merged arithmetic automatically is still an open problem. Last but not least, debugging is a very complicated task. Incremental verification and rectification techniques can be quite useful to help pinpointing the functional issue.

Model checking and property verification

Model checking and property verification are still a fraction of the formal verification market, with many players on the field. There are two obstacles for a larger usage of the approach. The first one is that it can be complicated to write a FSM or property that captures a particular behavior. SVA (System Verilog Assertions), OVL (Open Verification Library), and PSL (Property Specification Language) help in that regard, but they need to be more systematically used in the design community. The second obstacle is that model checking techniques can only solve relatively small problem instances. This is why some go with hybrid verification techniques (read: may be incomplete), like Magellan or 0-in, while other stick with complete formal methods, like Jasper and OneSpin.

Because writing properties can be so complicated, specialized branches grew to address specific needs, as shown below.

• IP verification. With SoCs using IPs from many different sources, verifying the compliance of these IPs with respect to standard interfaces (e.g., PCI or USB) in the context of the application is crucial.  Conformal, with its verification IP portfolio, is in a good position to address the problem. Also OneSpin is known to have interesting technology in that space, even though they are not pushing it at the moment.
• Timing verification. Incorrect timing constraints can lead to missing a target clock cycle, or worse, to a chip failure. Verifying timing exceptions (false paths and multi-cycle paths), as well as CDC (Clock-Domain Crossing), has become a center of attention. It is still unclear how big the market is. However several discussions with IC design companies led me to believe that verifying a set of timing exceptions (usually in the order of 10,000 SDC constraints) save one month work of an engineer. Automation and speed are keys here. Atrenta, Real Intent, and 0-in propose interesting solutions in that space.
• Power verification. When doing power gating, one needs to verify that the application is powered back up properly. Integration with UPF or CPF provides the required automation. Conformal and CPF have an edge in that field.
• Sequential clock gating verification. Traditional (combinatorial) clock gating is well supported by EC tools. Sequential clock gating exploits sequential dependencies to derive additional gating conditions, which can be used to save more dynamic power. It has been made popular by Calypto –Envis is also proposing a similar technique at the netlist level. Sequential clock gating correctness cannot be expressed easily with SVA or OVL without making the verification task extremely complex, which explained why specialized verification techniques have been developed.

Where formal verification will grow

Formal verification is no longer limited to ASICs: complex systems –SoC, FPGA, and HW/SW co-design— will benefit dramatically from better formal verification techniques if they are deployed adequately.

With the ever-growing size of FPGAs (Altera’s Stratix IV packs 820k logic elements, and Xilinx’ Virtex-6 has up to 750k logic cells), it is clear that simulation will no longer be sufficient to validate the correctness of programmable logic devices. The need for FPGA EC is real, and this requires complete automation and full support for retiming –OneSpin’s 360 EC FPGA has shown some competitive solution in that space. Also note that IP verification and timing verification apply to the FPGA designs too. The real question is whether FPGA designers are willing to pay for formal verification tools.

IP verification, and verifying the correctness of a SoC using IPs, is certainly a very strong driver for more sophisticated formal verification solutions. Power verification will become part of the ASIC design flow, as EC is part of the synthesis flow. Timing verification is still looking for its footing in the design flow –one question is the debug environment, which is still relatively limited, e.g., to showing waveforms.

Looking forward, formal verification techniques can be used (and have been used) in other fields than circuit design. Any critical digital system can benefit from formal verification techniques –transportation, medical equipments, security and privacy applications. The automotive industry is one of the most obvious targets. Cars are ubiquitous, they contains more and more electronics (representing about 30% of the end price today), and a functional bug can have very costly consequences. Cars rely on digital systems for anything from optimizing their engine’s efficiency to navigation systems, entertainment, and on-board diagnosis. Soon the intra-vehicle, vehicle-to-vehicle, and vehicle-to-roadside networking will fuel innovative products, driving the needs for fast development and the highest possible level of correctness. The EDA industry is taking notice, and Mentor has certainly taken the lead there. Whether they provide the adequate functional verification framework is another matter.

Formal verification will extend its reach by addressing the hard problems of EC (datapath verification, and retiming for FPGA), by being seamlessly integrated in the synthesis flow (power and timing exception verification), and by providing practical solutions to IP and hybrid HW/SW design verification.

Related posts:

1. Has formal verification technology stalled?
2. Formal verification stalling, take two
3. Automated low-power design flow is up for grabs (Part II)

Defect rate

First I would like to discuss the notion of software reliability and how it evolved over the past 40+ years. A defect causes an invalid behavior of a program with respect to its specification (e.g., incorrect output, performance issue, crash). One of many ways to look at software quality is to estimate its defect rate, i.e., the number of defects per line of code (loc), or more conveniently per 1,000 lines of code (kloc).

The first observation is that the larger the code, the higher its defect rate. It is estimated that the bug rate increases logarithmically with code size.

Source: Program Quality and Programmer Productivity, Capers Jones, IBM 1977

Thus the total number of defects for a specific application can be reduced by the following:

1. Continuous code factorization (direct loc reduction).
2. Use of libraries (which have a reduced bug rate, thanks to the extensive exposure they receive due to their long lifespan and high usage).
3. Increase the expressive power of the programming language (indirect loc reduction).

Since the introduction of FORTRAN in 1957, many languages and operating systems have been created and have grown more powerful and sophisticated. What could be typically coded in 10 klocs of FORTRAN can be coded today with less than 5 klocs of C++, and about 3-4 klocs of Java. Raising the level of abstraction of programming languages helps decreasing the total number of defects because it results in smaller programs with a lower defect rate.

Evidently, testing reduces the defect rate. A software powerhouse like Microsoft reports about 10-20 defects/klocs before QA, and claims that the rate drops to 1/kloc in released code. Looking at long lifespan and very critical code, statistic from the Jet Propulsion Laboratory shows that spacecraft software (which is typically only 20 klocs, and must run without interruption for years) reaches 6-10 defects/klocs after 2-5 years of testing. The code developed for the shuttle program is estimated to have less than 0.1 defect/klocs.

Source: Nikora, Allen P., “Error Discovery Rate by Severity Category and Time to Repair Software Failures for Three JPL Flight Projects”, Software Product Assurance Section, Jet Propulsion Laboratory, November 5, 1991″

Over the past 40 years, independent researches from academia and the private sector have shown that on average an application has a defect rate of 5.5/klocs, regardless of the programming language and the operating system used for development. This looks counterintuitive, since increasing the abstraction level of the programming language reduces the bug rate and the actual size of one specific application. But that progress is neutralized by the ever-increasing size and complexity of the programs, made possible by better software development methodologies and powerful development environments. To put a defect rate of 5.5/kloc in perspective, consider your typical EDA place-and-route product, say 3Mlocs of C/C++, with a likely high turnover rate (i.e., percentage of locs that are modified in every release). You can expect in the order of 16,000 defects…

Test-Driven Design

Now I will present a method that I successfully used for both existing and from-scratch products. It is based on the observation that independently from the quality of the team and the advancement of the tool, the software complexity and the unpredictable evolution of the product makes managing the software quality quite problematic. Think EDA, where customers ask for new capabilities every week and salespeople sell features 6 or 12 months before they are actually developed. It is difficult, if not impossible, to have an upfront, clean, and frozen specification, from which an architecture and a set of APIs can be derived. One needs to change the architecture and the APIs because of new unpredicted features and unforeseen problems, or simply because the software is written in a hurry without the adequate resources –I have no doubt that most readers will agree on that last point. This creates bloated code with a high defect rate, which result in application with a larger number of bugs.

Test-driven design flips the traditional software development scheme upside-down. In most cases, the software development flow consist of (1) specify the requirements in some language (e.g., English, ML, C++ or Java header files), and (2) iterate a code/test loop until the software reaches a point where it is deemed stable enough to go through a full QA regression release process. This often leads to slow iterations between the release team and the R&D team before the release is fully qualified. Also the essence of the original specification may be lost because there is no concrete way (read: operational semantics) to check whether the released product actually meets its intended requirements.

Traditional vs. test-driven software development flow

Contrast this with a test-driven design approach. In that methodology, the tests are written before anything else. The goal is to capture the specification with a set of small (positive and negative) unit tests. Then some code is written and run on the unit tests. Some of the tests fail, which lead to further refinement of both the unit tests and the code. This iteration write-test/code/test converges until one cannot design a new test that would break the code. The next step, QA regression release process, can then be carried on.

A few things are important to recognize in a test-driven software development methodology: (1) the spec is the set of unit tests; (2) therefore the release can be validated as meeting the spec; (3) the testing iteration handled by R&D is closed when the unit tests and the code are fully stable, which leads to fewer iterations between the release and R&D teams; and (4) this methodology does not assume anything about the intrinsic quality of the code and the strength of the development team. Indeed this approach can be used on very badly architected code and still lead to substantial improvements.  Also note that the unit tests can be internal, e.g., written in C++ and providing a self-testing mechanism, or more traditional with external data that are fed to the application.

Case studies

Let me give a few concrete examples. A tool I was in charge of contained some legacy code that performed an essential task in EDA: constant propagation (it consists of propagating logic values through a logic network, following basic computation rules, e.g., NOT(0) = 1, AND(0, 1) = 0, and AND(1, 1) = 1). The computational principles are simple, but a good constant propagation system should be lazy, incremental, support undo, may explain to the user why some constant occurs in some part of the network, etc.  This makes the development of the system much more challenging.

The legacy code produced crashes now and then. It was difficult to read, it contained suspicious piece of code to handle corner cases (e.g., multi-driver nets, user-set constants), and it had a poor testing coverage (<50%). I decided to go for a full rewrite with a clean API, and unit tests were developed together with the new code following a TDD methodology. This resulted in 6267 loc of C++, 40% of which being unit tests (click the screenshot of the C++ unit tests below), made of 1415 asserts. That code was release in May 2007, got 3 reported defects until November 2007, and has been without defect since then.

Another example is a C++ template’ized bitwise four-valued simulator, written to match the Verilog semantics. This was done with 8014 loc of C++, including 40% of unit tests, made of 1015 asserts (click the screenshot below: you can recognize the basic four-valued logic truth tables).  The template was self-tested with three different concrete instances of logic representation (on 2-tuples of bool, on strings made of 32 or 64 characters ’0′, ’1′, ‘x’, and ‘z’, and finally on an actual logic netlist).  No defect was ever found on the semantics.

In both these cases, I had the opportunity of rewriting or starting from scratch. What if one has to improve on an existing system too large to be rewritten?

The third example is about a complex feature (sequential clock gating) that at the time had been released 6 months before. The field complained about inconsistencies and erratic behavior, so I decided to apply a TDD methodology to rectify the code. First hurdle, we established a unit test campaign, which consists of describing the spec in terms of unit tests in plain English and sketches. This produced 49 unit tests, as shown below (click to enlarge).

Second hurdle, we proceeded to translate these informal unit test descriptions into elementary RTL descriptions. The idea was that if the code was compliant to the spec, we could predict exactly which optimized netlist it would produce. Third hurdle, a 3^rd party reviewed these 49 RTL tests, and found that 9 of them were faulty because they did not capture what was specified in the document. Once we fixed these tests came the fourth hurdle: we run the code.

The results were brutal: the code crashed on 3 tests, it synthesized a functionally incorrect netlist in 5 cases, and produced 13 suboptimal results. Overall, 21 failures out of 49 tests, a 43% defect rate! We then went through a 2 weeks iteration of unit test refinement and code fixing with a team that never touched the initial code, to eventually converge on 72 unit tests –many more than we could think of initially– and a usable feature.

Conclusion

Test-driven design (TDD) aims at capturing a spec with unit tests, then have some code successfully running these tests. The unit tests are more important than the code itself –any code that passed the unit tests meets the spec–. TDD initially requires a higher investment: writing unit tests to capture an expected behavior is a complex task, and a 3^rd party review is needed to validate them. But the effort pays off: eventually the set of unit tests becomes the spec, and can even be used as documentation. Running unit tests is fast, so it dramatically reduces the R&D testing time. Also once a code passes a comprehensive set of unit tests, the risk of iterating from QA back to R&D is reduced. Overall, test-driven design increases code correctness and stability dramatically, even in the presence of a deficient architecture and legacy code.

Related posts:

1. API design 101
2. Software outsourcing, a necessary evil
3. The formal verification market is still untapped

I also worked with already established products, with larger team and millions of lines of already existing code. The typical software management and development project always offers some cumbersome legacy code and API that survive years after years. The reason is not so much that people do not want to fix the problem, but that fixing the problem requires a major product architecture overhaul, which comes to a prohibitive cost. There are striking lessons in failed software architectures, and it all start with API design. I am sharing here my practical experience with C++ projects, but most of these advices also apply to Java.

Why is API so important?

An API can be a company’s greatest asset: it captures communication and exchange of services in an application. A good API will naturally lead to more reuse, simpler code, and lower maintenance cost. If the API is public, a good API will also capture customers. There are examples of Java libraries that failed to be accepted not because they were inefficient, but because they very poorly designed.

An API can also be a company’s greatest liability: once the service has clients, one can no longer change the API!  Suspending or rewriting an API is very pricey in terms of time and money. In the case of a public API, cost also comes in terms of reputation. A public API is forever: there is only one chance to get it right.

What is a good API?

In today’s object-oriented software, writing an API is providing a service. Thus instead of thinking in terms of implementation and efficiency, one must first think in terms of modules and services: determine the usage model; establish the clients’ needs; and anticipate tomorrow’s needs.

Besides being powerful enough to satisfy the requirements, an API should be designed with two principles in mind:

1. Keep it simple! An API must be easy to learn and use, even without documentation. The API must be hard to misuse. Functionality should be easy to explain –if it is hard to name, it is likely a bad function. Use simple, consistent naming, and the code will read like a prose –Java libraries and STL are good inspirations for naming conventions. The API should be as small as possible: you can always add to an API, but you can never remove. A method should not take more than 3-4 parameters –else wrap the parameters in a class that can be augmented later.
2. Keep it abstract! An API must allow extension for future needs. For example, it should not assume anything about the implementation. It should minimize accessibility to implementation-specific details –an API, once public, will be used, and you do not want to expose the ugly details of a database.

In theory, an API should be written before going into some implementation. Gathering requirements is the first step. Requirements must be case-driven, specific, and should be questioned relentlessly until proven to be must-have. The API should then be written in the target language (C++, Java, etc): this will force the development team to make choices, and to keep the API simple and abstract enough –nobody wants to have too much to discuss!  Then the API should be reviewed and made final in a public forum with the two principles above in mind: keep it simple (so that it is easy to support) and abstract (so that it is easy to extend).

An API should be documented, but well-designed APIs are sometimes self-explanatory. An API should answer the following questions about its components.

1. Class: what does an instance of a class represent?  Is that a singleton class?  Is there a factory?  Who owns the memory?
2. Method: what does it do?  What is the contract between the client and the instance?  Is there any precondition and post-condition?  Is there any side effect?
3. Parameters: what do they represent?  Which information do they carry?  Who own them?
4. Exceptions: who throw exceptions?  What do they mean?  What to do when catching one?

API and performances

Bad API decision can limit performances. When designing an API, it is good to consider the following rules.

1. Avoid mutability. If a method returns a mutable instance, that instance needs to be created somewhere, which raises the question of memory ownership. Also mutable classes limit thread-safeness. Use ‘const’ whenever possible.
2. Avoid implicit call to copy and assignment operators. This is a waste of resources if you can use references. Declare these operators ‘explicit’ or ‘private’ to catch any misuse at compile time.
3. A factory is often better than constructors. A factory has full control on how instances are created and when they should be released (shared model, garbage collection, save/restore, caching and disk mirroring, etc). A factory can return an instance of a sub-class.
4. Avoid exposing implementation details. It may prevent later improvements of a database. Never expose data members of a class, always use get/set accessors.
5. Question the thread-safeness of computational-intensive methods. One day the software may run on a grid or in a cloud.
6. Never compromise the rules above for a small runtime or memory improvement. For the vast majority of the applications, going a few percents faster is not worth the maintenance nightmare it can imply.

Final word

A good API is a key to produce smaller and simpler code, which makes the product more stable and easier to maintain. Designing a good API is a collaborative effort, and a formal decision process is needed to freeze an API. A good API is hard to write, get your best people on it. And finally, a public API is forever. May these simple rules guide your next project.

Related posts:

1. Test-driven design, a methodology for low-defect software
2. How to write abstract iterators in C++
3. Automated low-power design flow is up for grabs (Part II)