Points and Vectors

I’m gonna start off our discussion of Physics Engines with some posts about the Math that makes them tick. Don’t worry, I don’t have a degree in Math, so these posts will be long on rambling sentences, and short on Greek symbols. For this one I’m gonna skip the equations all together and just try to talk about the meaning of the most basic types in a Physics Engine: Points and Vectors.

There isn’t much that’s more fundamental to a Physics Engine then Points and Vectors. And for this reason, it’s important to spend some time getting them right. In my path to the Dubious Engine I have actually written a basic Vector library a handful of times. I even wrote one in Haskell to see if it did a better job of handling some of the awkward language edge cases that kept creeping up with C++. What is it about Points and Vectors that are so hard to get right? Well looked at from one angle, they’re pretty much exactly the same thing, 3 floats representing X, Y, and Z coordinates. But looked at from another angle, they have absolutely nothing in common. A Point represents a position in space, or where an object is. A Vector represents a direction and a magnitude, which isn’t really easy to summarize. Can you represent a Point with a Vector? Sure you can, like I said, they’re both 3 floats. But should you use the same class for both? I’d argue that you should not. Let’s discuss why.

Take a moment to consider addition. Does it make sense to add two Vectors together? Yes, absolutely, it’s entirely natural. If you had high school Physics I imagine you spent a lot of time adding Vectors. The mechanics are simple, you just add each of the three coordinates to each other. But what about Points? Does it make sense to add two Points? Surprisingly, no. Sure the math behind it is trivial, it’s the same as with a Vector. But does that have meaning? Let’s say you live in Philadelphia and I live in New York? Both of our positions in space can be represented as Points. But what does it mean to add Philadelphia to New York? It doesn’t mean anything. What would the locations of Philadelphia plus New York represent? I couldn’t even guess. So if addition of Points is meaningless, surely subtraction is too? Oddly enough, subtraction does have meaning. If you take Philly and subtract New York you are left with a Vector that defines the direction and distance from New York to Philadelphia. Remember that a Vector is a direction and magnitude. So this Vector’s direction would be South West, and the magnitude would be about 100 miles. Now if you start with the New York Point and you add this Vector, the result is the Philadelphia Point. Let’s summarize this:

  • Addition and subtraction of Vectors is correct
  • Addition of Points is meaningless
  • Subtraction of Points results in a Vector
  • Addition of a Point and a Vector results in a Point

This probably isn’t the result you were expecting when you first started thinking of Points and Vectors. I can tell you from experience that it took me many years to start thinking along these lines. Can you write a Physics Engine that ignores all of this and just uses a Vector for everything? Of course you can, my first few attempts did exactly this. However I found I was always creating bugs where I’d write an interface that expected a position, but I would eventually send it a Vector, and the whole thing would fail and I’d spend a lot of time trying to re-learn the algorithm to understand why. With this new representation I’m much clearer on the roles of Points and Vectors and it helps me keep things straight.

The Code

So with that in mind, how do we write the code? You could be tempted to just make them exactly the same thing, and just use a typdef to give them different names. After all, the actual mechanics of addition, subtraction, and equality are the same. But functions like get_length() make no sense with a Point, but are fundamental to a Vector, so it’s best to avoid this approach. You could be tempted to use inheritance, and move the common functionality to the base class Point and put the Vector specific functionality in the Vector. This is a little cleaner in that you can reuse common code, but the polymorphism is awkward because inheritance represents an “is-a” relationship, and as discussed above, a Vector is not a Point. Another trick you could try is composition, where a Vector just contains a Point, but this leads to circular dependencies in your code. In order to implement Point subtraction a Point must depend on a Vector, but in order to implement a Vector it must depend on a Point. This will really piss off your compiler, which is generally not a good thing to do.

So this leads us to the solution I ended up with, a third class called a Triple, which is nothing more then an abstract thing that contains 3 floats. This Triple isn’t even a class, it’s just a lowly struct, and it implements the absolute basics, addition, subtraction, and equality. Both a Point and a Vector contain a Triple, and a lot of their basic functions are implemented as a simple pass through. They both build on the Triple to implement their type specific functionality.

Now that you understand my reasoning behind Points and Vectors, it should be pretty easy to understand the code. Here are links to my Triple, Point, and Vector implementations. For now, ignore the templates, we will discuss their usage later.

  • Triple – Simple struct of 3 floats. Handles basic math and equality
  • Point – Represents a 3D point in space.
  • Vector – Represents a direction and magnitude.
 << See Also Contents  Vector Types >>

See Also

I think it’s typical to put the Bibliography at the end. However for this series of posts, I’m putting it right at the start. The reason for this is because the Dubious Engine is in no way an original piece of work. I did not invent any of the Physics that powers it. I’d like to think that I’ve organized it in a way that makes it easy to understand and write about, but I certainly didn’t come up with any new algorithms. Everything here has been described somewhere else. Unfortunately I started this so long ago that I’ve lost track of all the things I’ve read, but here are the ones that I can remember:

  • allenchou.net – This is the big one, I must have read and re-read every post here dozens of times. If he had source code to post I probably wouldn’t have bothered writing anything.
  • 3D Game Engine Programming – The site that finally got me to understand Quaternions. That alone makes it priceless, all the other great articles are just a bonus.
  • box2d.org – The simplest code to understand, primarily because it’s in 2D. It’s almost a requirement that you get it running and familiarize yourself with it while creating your own Physics Engine. While it is not 3D, the concepts are familiar enough. Also contains some papers that you have to be much smarter then I am to understand.
  • bulletphysics.org – An actual, working Physics Engine, complete with source code. It does everything. Unfortunately it’s very difficult to read through and the documentation is sparse. Still, if you have the time to really truly go digging, the answer is in there.
  • Molly Rocket – In 52 minutes you can understand what the GJK algorithm is. Other articles can help you refine it, but really there is no quicker path to understanding.
  • Code Cave – Second only to Allen Chou for understanding GJK and EPA. Bonus points for representing 3D concepts using sticks and putty. I may very well rip that off.
  • dyn4j.org – More great information about GJK and EPA
  • Matrix and Quaternion FAQ – One of those ancient pages out of Internet history (hello purple.com). I can’t find the original version I used to use, but this seems like it’s pretty much the same thing. This is where I was introduced to Quaternions, and my first implementations came from this page. It was so freaking painful.
 << Introduction Contents  Points and Vectors >>

Building a Physics Engine

“You’re Building a What Now?” Before thinking about building a Physics Engine, you have to stop and ask yourself a very important question, “why on Earth would you want to build a Physics Engine?” In many respects, a Physics Engine is a solved problem. There are really good ones available, open source, for free (thank you Bullet). Unless you’re a PhD with some fancy new algorithm to try out, you’re not gonna beat any of the existing engines. So why bother?

I didn’t start out trying to build a Physics Engine. I started out (back in 2001) trying to build a really cool space dog fighting game. I didn’t have any really original ideas, but I wanted to combine all of my favorite bits from various games of the genre, and see what I could make. I knew I would never be able to complete it, but I thought it would be interesting to try. As different aspects of the game started coming together, I would occasionally read people mentioning Physics Engines, but I always figured they just weren’t very smart. Everyone knows Physics, right? v=d/t like from High School. I just coded that up and got back to work. But as the game started to take shape, I noticed that ships didn’t move right. Like if you shot a missile into a wing tip, the whole ship would lurch backwards, instead of going into a spin. So I started reading a bit more about the mysterious Physics Engines. Eventually I became so engrossed I stopped working on the game at all, and just learned Physics.

So this brings us to today. I have found that the world of Physics Engines falls into two categories:

  1. Well written articles, but not enough detail and no code.
  2. Code with absolutely no explanation.

So here’s the pitch. I have written a basic but functional Physics Engine. Now I’d like to write about it. The goal is to produce blog posts, that together with the source, will create the world’s first understandable explanation of a Physics Engine. This should be the guide I always wished was available to me.

Let me throw out some buzzwords to explain what it is I have to write about. I’ve written a Rigid Body, Discrete Engine. I use GJK and EPA to do my collision detection. And I wrote a Sequential Constraint Solver to do collision resolution. If you don’t know what any of those terms mean, that’s fine, we’ll go over them all. If you’ve come here looking for information on any of those, then you’re in luck, ’cause that’s what I got.

I call it the Dubious Engine. The full source is available online at: https://github.com/SaintDubious/DubiousEngine. I will try to refer to the actual source with each blog post, so you can see working code, and follow along with the reasoning behind each piece. I hope you find this information useful as you work to create your own Physics Engine. As for my initial question, “Why on Earth would you want to build a Physics Engine?” Simple answer really, it’s a lot of fun.

Contents  See Also >>

Table of Contents

Welcome to the Dubious Engine. This series of blog posts is my attempt to fully explain how to write a basic Physics Engine. The full source is available at: https://github.com/SaintDubious/DubiousEngine

Table of Contents

  1. Introduction
  2. See Also: References
  3. Math
    1. Points and Vectors
    2. Vector Types
    3. Vector Math
    4. Rotations
    5. Using Types to Your Advantage
    6. Coordinate Systems
  4. Physics
    1. Linear Motion
    2. Angular Motion
  5. Collision Detection
    1. Collision Detection – GJK 1
    2. Collision Detection – GJK 2
    3. Collision Detection – GJK 3

That’s all for now. Writing these takes time, so it might be a while, but here are some other ideas:

  1. Collision Detection – EPA
  2. Collision Detection – Contact Manifolds
  3. Collision Response – Constraint Solver
  4. Collision Response – Friction
  5. Broad Phase Collision Detection
  6. Cheats – Baumgarte and Coefficient of Restitution
  7. Cheats – Warm Starting
  8. Optimization – OpenCL

Switch on Type Construction

Many years ago I had a non-technical manager who was amazing. If you’ve been in the field long enough you’ll know that this is a rare and wonderful thing. One of the things that made this guy special was how he handled the yearly review process. Maybe I should tell you how every other company’s review process works so you can compare and contrast. Here are the steps for every other company:

  1. Fill out a humiliating form boasting about everything you did during the year because it’s apparent that your manager barely remembers who you are. Make sure you add a section about your failures so everyone will know you’re humble.
  2. Meet with your manager so he can tell you how amazing you are for a while.
  3. Then learn that despite how amazing you are and how awesome the company is, learn that there’s no money for raises because of convoluted financial magic.
  4. Receive disappointing raise with vague talk about how it might possibly be larger next year.

So compare that with my amazing manager who absolutely knew who you were and had clearly done a lot of work to create a review process that he thought would be useful. No forms to fill out. He’d ask you to come up with a handful of technical goals you wanted to achieve, and a handful of non-technical goals. That’s right, not only did he want to help you become a better programmer, he’d also play coach for anything else you wanted to do. Some people came to him with lists of things like “learn to cook” or “get motorcycle license” and he’d absolutely help you set milestones to accomplish those goals too.

So one year when it was my turn for the yearly review, I told him I wanted to learn how to use Design Patterns. Like most every programmer, I’d read the Design Patterns book, but I never could figure out why it was useful. I basically memorize them all when it’s time to interview for a new job, and promptly forget about them. So my manager gave me the task of learning a new design pattern that wasn’t in the book. This sounded interesting enough and after a little research, I came across what I call the Switch on Type Construction pattern, and this (finally) brings me to the point of this post.

Warning: I was recently horrified to learn that this solution does not always work, depending on compilers, optimizers, environments, etc. But it’s still awesome so I’m keeping the post. But be careful with it.

Often in C++ you end up in a situation where you want your code to do something different based on the type of the class. This is called “Switch on Type” and it is a “bad thing.” This phenomenon is so well known it’s a classic case of why we have classes in the first place. Here’s some code to demonstrate, let’s say you have something like this to handle images:

void render( Image* obj )
    if (get_extension(obj->file_name()) == "jpg") {
    else if (get_extension(obj->file_name()) == "png") {

This is bad because as the list of formats grows, you’re constantly back in here cutting and pasting to the list, and probably introducing bugs, etc. This situation was solved with virtual functions: a base image type, and then a subclass of Jpg and Png image types. So the previous code just turns into something obvious like:


where the render_image function is virtual in the base type, and then overridden to do the correct things in the subclass.

This is all well and good, but what do we do with object creation? You can’t use virtual functions in a class that hasn’t been constructed, and there’s no such thing as a virtual constructor.  Our task for this post will be to create an appropriate image object depending on the file type (and we’ll assume that the type is correct and ignore errors).

So let’s take our starting point as this:

class Image { /* blah blah constructors, functions etc */ };
class Png_image : public Image { /* blah blah */ };
class Jpg_image : public Image { /* blah */ };

std::shared_ptr<Image> create_image( const std::string& file_name )
    if (get_extension(file_name) == "jpg") {
        return std::shared_ptr<Image>( new Jpg_image( file_name ) );
    if (get_extension(file_name ) == "png") {
        return std::shared_ptr<Image>( new Png_image( file_name ) );
    throw std::runtime_error( "Unknown image type" );

Does that seem like some code you may have written in the past? I know it’s definitely something I have written. Any why not? It’s short, concise, solves the problem, etc etc. Who cares that every time we need to add a new image type we have to update this function? Well what if I told you there’s a pattern that lets you add new image types without recompiling existing code? “Impossible” you’d say, and you’d be wrong.

The first thing we’ll need to create for our awesome solution is an object creation map. This is a map that uses our image type (either “png” or “jpg”) as a key and a creation function as a value. With this we can simply use the image type to find the correct creation function. Of course this map will need to be a singleton as we only want one of them in the whole program. Let’s expand our Image class to include:

  • Typedefs for complex types
  • The creation map
  • Accessors to this map
class Image {
    static void register( const std::string& ext, Creation_func& func)
        function_map()[ext] = the_function;
    static std::shared_ptr<Image> create( const std::string& file_name )
        return function_map()[get_extension(file_name)]( file_name );
    typedef std::function<std::shared_ptr<Image>(const std::string&)> 
    typedef std::map<std::string, Creation_func> Function_map;
    static Function_map& function_map()
        static Function_map singleton_map;
        return singleton_map;

First consider the Creation_func typedef. It defines a function signature for a function that creates shared_ptrs of Image. Such a function might look like std::shared_ptr<Image> create( const std::string& file_name ). This Creation_func is combined with a file extension (ie “png” or “jpg”) to make a Function_map. Then there’s a function_map() accessor, and a function to add entries to the map, and a function to create an actual image. Let’s see how our code could now use this to get rid of the “switch on type” issue:

// functions defined elsewhere
std::shared_ptr<Image> create_jpg( const std::string& file_name );
std::shared_ptr<Image> create_png( const std::string& file_mame );

// register them in the map
Image::register( "jpg", create_jpg );
Image::register( "png", create_png );

// and use them in your code
std::shared_ptr<Image> jpg_image = Image::create( "file_name.jpg" );

So that’s a pretty cool start. We no longer have the if (extension_check) { return Image; } mess that we had before. But it’s still not terribly easy to use. Now if we wanted to add support for a third image type we’d still have to edit our code and add a call to register. Still, we could stop right here and have a much better solution… or we could add templates to make the whole thing better.

Enter Templates

What we want to do to make this solution better is to create a system wherein new image types can be added to the code without recompiling anything. That’s sort of the holy grail of system extension. That means no testing of any existing code because the existing code won’t change. Heck you could take your existing object files, compile in the new image classes, link the whole thing together and magically have support for new types. Sounds like a trick to strive for. So to help us out we want to add a template class that acts sort of like a factory. Here’s how it looks:

template <class T>
struct Registration_object {
    Registration_object( const std::string& ext )
        Image::Creation_func f = Registration_object<T>::create;
        Image::register( ext, f );
    static std::shared_ptr<Image> create( const std::string& image_name )
        return std::shared_ptr<Image>( new T( image_name ) );

So what’s going on with this one? Well it has a static create function that simply creates a new Image of the templated type T. It also has a constructor that will add a pointer to that create function into the singleton function map.

So how do we use this new registration object? All we have to do is create exactly one of these for each image type, and it will automatically register that new type in the map. So let’s change our usage code to use these instead:

Registration_object<Jpg_image> jpg_registration( "jpg" );
Registration_object<Png_image> png_registration( "png" );

std::shared_ptr<Image> jpg_image = Image::create( "file_name.jpg" );

That’s starting to look pretty awesome. Now we just have to create one global variable that we never directly use, and our image type is magically added to the map. So how can we use this trick to add an entirely new image type without recompiling existing code? Hold on to your hats, cause this is the amazing bit. I’m not going to touch the code above (ie I will not recompile it) but I can add Gif support by simply adding the following in a separate .cpp file:

class Gif_image : public Image {
    Gif_image( const std::string& file_name ) { /* Gif image stuff*/ }
Registration_object<Gif_image> gif_registration( "gif" );

Did you see it? Now when this new .cpp file is compiled and linked with the existing object files, your program will suddenly be able to deal with gif images. The reason this works is during static object creation time (before main starts) an instance of this new Registration_object<Gif_image> will be constructed, and during that construction it will register its create function with the static function map. If that doesn’t impress you then stop reading this blog and fuck you.

Oh, and what about that manager I had? He helped me reach a number of goals, both technical and non. Eventually the company merged with another one and he was replaced with the HR lady from the other company. The first thing she did was bring in those damned yearly evaluation forms like every other company has. I was more then happy to quit that job.

Static Creation Functions

When I wrote about Class Construction, I noted that of all the incorrect arguments about constructors not being sufficient, there were a handful of cases that are actually correct. While not an exhaustive list, here are some cases that spring to mind:

  1. If you are creating a class hierarchy wherein a base class defines a number of virtual functions that subclasses are meant to implement (like on_create). It’s not unreasonable to try calling a virtual function in the base class constructor and expect a subclass function to run. Unfortunately this won’t work. The v-table won’t be set up yet, so attempting to call a virtual function will in turn call the base class’ implementation.
  2. If you want to enforce HOW your objects are constructed. While it’s not possible to force all your classes to only be constructed on the stack, it is possible to force clients to only create objects as smart pointers (or raw pointers if you’re a big fan of resource leaks).

In both of these cases it won’t work to simply expect your clients to use the regular constructor. For case 2 you could solve this by adding documentation that says “please don’t create these on the stack” but if your code depends on developers actually reading the comments then it’s already doomed. You could solve case 1 by using an initialization function, but then you’d be totally ignoring all the great advice in the post that told you why that’s a horrible idea.  So what’s left? This is a perfect situation for a static creation function, which looks like this:

class Some_class {
    static std::shared_ptr<Some_class> create();

So what’s going on here? Well, the first thing to notice is that it’s a static function, which is a pretty important aspect to this technique as it means you can call the function without having created an instance of the object (because if you need the object to exist before you can create it, it’s probably not gonna work). The next thing to notice is that I have control over the return type, which in this case is a shared_ptr. You can imagine other return types (or even void if you need to enforce that the object must be created into some global store that you access in some other way).

At this point you may be pointing out that while this is all fine and dandy, there’s still nothing to stop anyone from just creating an instance of Some_class directly and avoiding the create function.  You’d be right. The second half to this trick is that you have to make your constructor private. It will still be accessible inside the create function, but it won’t allow users to create your object any other way. So here’s a more complete example:

class Some_class {
    static std::shared_ptr<Some_class> create()
        std::shared_ptr<Some_class> ptr( new Some_class);
        return ptr;
    Some_class( const Some_class& );
    Some_class& operator=( const Some_class& );

I don’t generally put the code in the actual header, but it makes the example easier to read. Notice that along with the constructor I also made the copy constructor and operator= all private. There is now no way to create one of these things without using the static create function. Here’s how you’d have to make one:

    std::shared_ptr<Some_class> ptr = Some_class::create(); // OK
    Some_class stack_instance;           // won't compile
    Some_class copy_construct( *ptr );   // won't compile

Pretty sporty, huh? Take some time to soak this in, controlling an object’s construction is awesome and definitely needs to be a part of your toolkit.

Now you may also have heard about factories.  A factory is a lot like a static creation function, but it exists as a separate class, adding a level of abstraction. I even had a co-worker who used to go on about how factories should actually be interfaces, so you could have entire hierarchies of factories that you could swap out to get different kind of creation functions. This all sounds well and good and impressive and fancy, but in practice I’ve never been in a situation where a static create function wasn’t good enough. Class factories always seem like going too complex for me. But as I’ve stated before, I’m not terribly clever, so if you really want to create a factory (or an entire inheritance tree of factories) then go right ahead. Just make sure you make your object’s constructors private to ensure people don’t just bypass the whole thing.

Some bullet points:

  • Occasionally (rarely) a constructor is not sufficient
  • Create a static function called “create” that does exactly that
  • Make your object’s other construction functions private
  • You can use class factories if you want to be a smarty pants

Exceptions are Awesome

Welcome to the year 2015. Obamacare is the law of the land, gay folks can get married, C++ has lambdas, and (this will surprise some folks) exceptions are the correct way to report errors. The fact that I still have to argue this point is, frankly, shocking. I don’t care that the Google style guide doesn’t allow them, and for the love of God don’t tell me they’re inefficient. Simply put, they are the way to report errors, you must know how to use them.

Now to some extent I actually sort of sympathize on this one. When I learned C++ (back in 1995 or so) exceptions weren’t widely used. And even up until around 2005 I was pretty convinced that they were a bad idea. But I’m old and that was 10 years ago… what’s your excuse? Some programmers today seem to have the same misconception I had in 2005, so let’s walk through the faulty logic. They argue that using exceptions makes code bloat substantially. They start with something like this:

return_code = blah();
if (return_code != SUCCESS) {
    return return_code;
return_code = something_else();
if (return_code != SUCCESS) {
    return return_code;

And apply exceptions by turning it into this:

try {
catch (const std::exception& e) {
    throw runtime_error( "calling blah failed" );
try {
catch (const std::exception& e) {
    throw runtime_error( "calling something_else failed" );

And then argue that using exceptions has turned an 8 line function into a 12 line one. But they’re missing the point. So I’ll write down the point in bold letters: throw an exception when an error occurs, and catch an exception when you can do something about it. Armed with this knowledge, most junior programmers will head back to their keyboards and come back to me with something like this:

try {
catch (const std::exception& e) {
    throw runtime_error( "calling blah or something_else failed" );

Well now we’re down to just 7 lines, so this is a step in the right direction, but it’s still wrong. Let’s take a look at the correct answer and then discuss why it’s correct


Ah, much better. Now we’re just down to 2 lines, and better yet, we don’t have to worry about errors at all. We have two short, succinct lines that just assume the best case scenario and ignore errors completely, what could be better? “But wait, this can’t be correct, there’s no error handling at all!!!” And that’s the point. Take a look at the second part of the bold statement above, catch an exception when you can do something about it. In all of these examples there was nothing sensible we could do in the case of an error but just return an error up to the caller. Since an exception just naturally bubbles up the call stack, and since there’s nothing I can do about it here, just let it bubble up the call stack.

Do you see the beauty in that? Are you reading this and having a warm and tingly sensation rubbing your chest? If not, think about it some more. You are now free to write code where you don’t have to nit pick every single error case. By way of example, let’s say you’re writing some kind of web server. A request comes in for a web page and in order to respond you’ve got to hit a database for some content, the disk for some assets, and then maybe execute some business logic to tie it all together (God help you if it’s Ruby on Rails). Somewhere deep down in the bowels of your db connection something might go wrong. Do you really want to have to watch error codes at every function call and have to keep translating them as they work their way up the stack through multiple layers of return codes? Of course not, none of the intermediate layers can do anything anyway, the db is dead, they can’t fix that. Imagine a world where the db fails and the highest layer is simply notified so it can return a bland 500 error to the client. That’s the joy of exceptions. The db layer throws an exception, every layer in between ignores it, and the top layer catches it and returns. But wait, it gets even better. The system unwinds the stack for you, correctly destroying all the objects you created along the way. Sound awesome? That’s because it is awesome.

Oh but wait, isn’t it expensive? Well yes, it is, but that doesn’t matter. Why doesn’t it matter? Because exceptions are for exceptional cases. Take the case of our http server above. How often do you think a database blows up? Okay okay, I get the joke, almost constantly, but seriously, in the normal day of operations, how often? It’s an unusual thing, so who cares if it runs just a tiny bit slower? Users aren’t gonna be sitting on their web browser complaining that their 500 error page took an extra picosecond to return. In the normal run of things, exceptions don’t happen, so you don’t pay a performance penalty.

Of course this is only true if you don’t abuse exceptions. You need to make sure that you’re not using exceptions to report back something that is expected behavior. Let’s say you’re writing some function bool lookup_something_in_db( int id, Thing& thing_copy ). This function looks up a Thing in the db with the given id. It seems to me that the thing in the db might not exist. Or to say it in a more obvious way, it’s not an exceptional case that the id doesn’t find something in the db. So using an exception to return information that the thing doesn’t exist would be a really bad idea, you’d be throwing exceptions for cases that are expected. In this case returning a bool to notify the caller that thing they were looking for doesn’t exist is a good idea.

So here’s the bullet points:

  • Exceptions are awesome, use them
  • Throw when an error happens, catch when you can do something about it
  • Don’t use exceptions for expected, normal processing

And further reading

Class Construction

I’ll start with a story. Years ago I was starting out at a little software shop, trying to learn my way around the existing code base. As is usual in these cases, everything I encountered looked bad to me. As I’ve grown a bit as a programmer I’ve learned to realize that some of this feeling comes from simply not understanding the constraints on a given system, and some of this comes from actually encountering bad software. So of course many spirited discussions followed wherein the head of software would defend the code and I would try to tear it down. I think one of the primary goals of a library is that it should be “easy to use correctly and hard to use incorrectly” – Scott Meyers (see below). While I admit that this is not always achievable, it should at least be a goal. He stated emphatically that his library had done a good job of this. So imagine my revulsion when I stumbled upon something like this:

class Some_class {
    bool initialize();
    bool startup();
    void set_some_member( const std::vector<int>& member );

Have a longer look at this one and ask yourself if this is easy to use correctly. If you think it is then look again and ask yourself how to create an instance of Some_class. I asked this exact question and he told me it was obvious and I should look for some examples. So I did. I learned that the correct way to create an instance of Some_class is to first call the constructor (obviously), then call set_some_member (huh?), and then call startup. Also, for the love of God, whatever you do, never call initialize because that leads to undefined behavior.

So this leads me to the point of this post, which is that of all the things your object needs to do, construction is really fundamental. As a corollary to this, initialization functions are awful. Now I can already hear the more senior types pointing out that there are cases where a constructor alone simply cannot do the job. You’re correct, that is true, and in time we’ll be looking at some of those. However there are a whole other set of incorrect cases that junior developers mistakenly think justify initialization functions (and other horrors). We need to end this misconception.

The most pervasive incorrect case is when someone thinks that because there’s no way to return a status code from a constructor, you need an initializer function to truly bring your object to life. In this anti-pattern the constructor does the basic member initialization, which can not fail, and then the initializer does the dangerous work, returning a success code if everything went okay. This leads to two major problems. The first is for the users of this class. They will skim your documentation just enough to find some function they like, and the constructor, and immediately set about creating it and using it. Maybe this will kind of work without calling the initalizer, or maybe it won’t. When something eventually fails, they’ll be annoyed. But more importantly, this object will be hard for you to write because you’ll invariably have to hold some internal flag to check whether or not initialize has been called. Then you’ll need to worry about what happens if someone calls initialize twice, and blah blah blah it’s just not worth it.

In order to stay out of this quagmire you need to know one simple thing: it is correct to throw exceptions from constructors. Many of the junior programmers I speak with don’t know this simple fact. Often they’ll hedge their bets by telling me the code will compile, but it’s not the correct thing to do. They’re wrong. Throwing exceptions from a failed constructor is exactly the correct thing to do. In fact it’s the only way to safely let the calling function know about failed construction. But then what’s the state of an object that throws an exception halfway through construction? Simple, it doesn’t exist, it never did. Objects don’t exist until construction is finished, so if construction doesn’t finish, the object doesn’t exist. Will the destructor be called?  No, it most certainly will not. How can you destruct an object that was never constructed? Another question I often get is, doesn’t this lead to memory leaks?  The answer is: only if you’ve written a constructor that isn’t exception safe. But this has nothing to do with constructors and is simply a fact of writing any function that isn’t exception safe. You should never have a function that allocates anything and just assumes that no exception will ever be called.

C++11 Note: In C++11 we now have delegating constructors. This means a constructor can call another constructor. This makes it a little less clear about when an object is constructed. The rule is that when the first constructor is finished, the object has been created. So now if an exception is thrown from the calling constructor (after the called constructor is finished) the destructor will be called.

So there you have it, end of lesson. Here’s the summary in simple bullet points:

  • Never ever ever ever write an initialization function
  • If something goes wrong during construction, throw an exception
  • If an exception is thrown during construction, the object never existed (the destructor won’t be called)
  • Don’t write functions that aren’t exception safe (constructors or otherwise)

Further reading:

Welcome to DubiouSoft

This is the place where I like to write about various technical things. A while ago I created this site in an attempt to mix mid-level code reviews with blatant, overbearing profanity. However after a few posts like that I decided that the world has enough angry old programmers. So now I’m pressing the reset button and bringing it back to being just a site about programming. I think I’ll probably clean up the old code review posts, because some of them hit on points that I find myself repeating a lot (without the profanity), so maybe it would be good to have them online as reference. I am hoping to also find the time to write about my experience with Physics Engines, because I have spent far too much time writing Physics Engines and I would love to spread some of the tedium with the world at large. I’m not sure what other things I can write about, but it’s nice to have a place to pontificate from time to time. So welcome to DubiouSoft, I hope you find something of interest.