The high level architecture that I’ve developed over the years has 3 layers:

 ________________________
|                        |
|      Core Game         |
|________________________|
            |
 ___________V____________
|                        |
| In-house Game Library  |
|________________________|
            |
 ___________V____________
|                        |
|  3rd party libraries   |
|    - Sound             |
|    - Graphics          |
|    - GUI               |
|    - ...               |
|________________________|

The Core Game only contains code specific to the game. Try to move as much generic code to your in-house game library, this way you can reuse it when you’re working on other games.

The in-house game library contains on one hand the generic code that can be shared between multiple games, and on the other hand acts as a facade on top of 3rd party libraries. This means that the core game never calls the 3rd party libraries directly, but always passes through your in-house game library.

Advantages

Since your core game is only using your own inhouse game library, you have total control over the API that it calls. Switching 3rd party libraries or custom made has no impact on the game code. You can also extend the external libraries with some functionality that you can write on top of them. When interface changes are made in newer 3rd party libraries, you don’t have to find/replace in your game code, adapting the in-house game library is enough. Porting multiple games also becomes easier, because once your in-house game library is ported, no major adaptions are needed in the core games.

Koen Witters

Follow me on twitter

• To get as many customers as possible, use an engine that supports multiple platforms: Windows, Mac and Linux.
• To make the best use of your time, prefer higher level scripting languages over lower level programming languages.
• Paying for an engine doesn’t necessarily mean that you get a better product or better support.

My personal favorite? Pygame of course!

Let’s assume we’re programming a racing game, and we have a class called RaceCar. Soon enough that class will contain a method to update it’s state, to draw it onto the screen, to accept user input, etc. It will become huge with all kinds of different functionality in there. So how can we divide up our game so it’s nicely split up into modules and classes? Just read on and learn .

Step 1: Split up the game into logic and rendering

Concept

The first thing we should do is decouple the rendering from the logic. And this makes perfect sense. If you take look at my game loop article, we can even let the game logic run at a different speed than the rendering.

The game logic will know nothing about the rendering, so it doesn’t matter if it will be displayed in 2D, 3D, ASCII art or whatever. The rendering however depends on the logic, because it needs info on how/where to display everything. The following figure shows the 2 modules with their dependencies. The rendering happens inside the “View” module.

     _________          _________
    |         |        |         |
    |  Logic  |<-------|  View   |
    |_________|        |_________|

Example

What this means in practice is that we will create a RaceCarView class next to our RaceCar. RaceCar handles the logic and user input, and knows nothing on how to display it, and RaceCarView displays the race car on the screen, using information from RaceCar.

Problem with interaction

When our car is controlled by a joystick or keyboard this concept works out just fine. But assume we want to mouse click on an opponent car to take over its control. If our logic knows nothing about the view, we don’t know on which car the user clicked. So in this case our logic also needs to query the view, which creates a circular dependency, and we don’t want this. Lucky for use we can get rid of this by doing another split, explained in the following section.

Step 2: Split up the logic into model and controller

Concept

The second thing we can do is further split up the logic into a model and a controller. The model is basically the game world, it knows nothing about displaying, user input, etc. It just implements all the world rules, and how entities interact with each other. The controller knows about the model and can manipulate it. For example the controller checks the user input, and manipulates the car accordingly. As we saw in the previous section, the controller needs to query the view when using mouse input for manipulating on-screen objects. And thanks to the split up, the model doesn’t have any dependencies like the logic had.

           ________________
          |                |
          |   Controller   |
          |________________|
            |            |
            |            |
            |            |
      ______V__        __V______
     |         |      |         |
     |  Model  |<-----|  View   |
     |_________|      |_________|

Example

In our RaceCar example, we will extract our user input handling into a new class RaceCarController. When the user presses the left-button, the controller sees this and calls the model’s RaceCar.steer_left(). The model then handles the world rules of the car going to the left.

Where to put the AI?

Most games use an AI to control certain game objects, so the question is where to implement this, in the model or the controller? The answer is pretty simple: if the AI controls the same object in the same manner as the user does (i.e. a ‘bot’), implement it in the controller. In the other case, it’s part of the game world so you should implement it in the model. In our example the car AI’s should be implemented in the controller, because they are basically bots. If we would have pedestrians that jump out of the way, they would be implemented in the model, because they are part of the world.

Summary

So after dividing our code up we get 3 separate modules: the model, the view and the controller.

Model

All the rules of the game world are implemented in the model, and it also contains the state data of every game object or entity. It is a pure game world simulation, so it doesn’t know anything about user input or displaying to a screen.

View

Rendering to the screen is handled by the view. It uses the model to know where to draw everything. The view doesn’t have any other functionality than this.

Controller

The controller handles the user input and manipulates the model. First it checks for user input, then it might query the view to see which on-screen objects are being clicked by the mouse, and finally it manipulates the model. Multiple controllers can be implemented, for example a keyboard controller, joypad controller, and even AI ‘bot’ controllers.

The model is standing on it’s own and doesn’t need to know anything about the others. The view depends only on the model to render everything on the screen. The controller receives input, can gain additional information by calling the view, and at the end manipulates the model. The advantages of this architecture:

• Nice modular design
• Game world logic is nicely bundled in the model
• Changes in rendering doesn’t impact the core game
• Supports different input controllers and/or bots

           ________________
          |                |
          |   Controller   |<============ User Input
          |________________|
            |            |                    O
            |            |                   /|\
            |            |                   / \
      ______V__        __V______
     |         |      |         |
     |  Model  |<-----|  View   |=======> Screen Output
     |_________|      |_________|

Koen Witters

Follow me on twitter

Thanks to my job as a game programmer, I come into contact with a lot of code for small mobile games. And it always amazes me how many game loop implementations are out there. You might wonder yourself how a simple thing like that can be written in different ways. Well, it can, and I will discuss the pros and cons of the most popular implementations, and give you the (in my opinion) best solution of implementing a game loop.

(Thanks to Kao Cardoso Félix this article is also available in Brazilian Portuguese)

The Game Loop

Every game consists of a sequence of getting user input, updating the game state, handling AI, playing music and sound effects, and displaying the game. This sequence is handled through the game loop. Just like I said in the introduction, the game loop is the heartbeat of every game. In this article I will not go into details on any of the above mentioned tasks, but will concentrate on the game loop alone. That’s also why I simplified the tasks to only 2 functions: updating the game and displaying it.

Here is some example code of the game loop in it’s most simplest form:

    bool game_is_running = true;

    while( game_is_running ) {
        update_game();
        display_game();
    }

The problem with this simple loop is that it doesn’t handle time, the game just runs. On slower hardware the game runs slower, and on faster hardware faster. Back in the old days when the speed of the hardware was known, this wasn’t a problem, but nowadays there are so many hardware platforms out there, that we have to implement some sort of time handling. There are many ways to do this, and I’ll discuss them in the following sections.

First, let me explain 2 terms that are used throughout this article:

FPS

FPS is an abbreviation for Frames Per Second. In the context of the above implementation, it is the number of times display_game() is called per second.

Game Speed

Game Speed is the number of times the game state gets updated per second, or in other words, the number of times update_game() is called per second.

FPS dependent on Constant Game Speed

Implementation

An easy solution to the timing issue is to just let the game run on a steady 25 frames per second. The code then looks like this:

    const int FRAMES_PER_SECOND = 25;
    const int SKIP_TICKS = 1000 / FRAMES_PER_SECOND;

    DWORD next_game_tick = GetTickCount();
    // GetTickCount() returns the current number of milliseconds
    // that have elapsed since the system was started

    int sleep_time = 0;

    bool game_is_running = true;

    while( game_is_running ) {
        update_game();
        display_game();

        next_game_tick += SKIP_TICKS;
        sleep_time = next_game_tick - GetTickCount();
        if( sleep_time >= 0 ) {
            Sleep( sleep_time );
        }
        else {
            // Shit, we are running behind!
        }
    }

This is a solution with one huge benefit: it’s simple! Since you know that update_game() gets called 25 times per second, writing your game code is quite straight forward. For example, implementing a replay function in this kind of game loop is easy. If no random values are used in the game, you can just log the input changes of the user and replay them later.

On your testing hardware you can adapt the FRAMES_PER_SECOND to an ideal value, but what will happen on faster or slower hardware? Well, let’s find out.

Slow hardware

If the hardware can handle the defined FPS, no problem. But the problems will start when the hardware can’t handle it. The game will run slower. In the worst case the game has some heavy chunks where the game will run really slow, and some chunks where it runs normal. The timing becomes variable which can make your game unplayable.

Fast hardware

The game will have no problems on fast hardware, but you are wasting so many precious clock cycles. Running a game on 25 or 30 FPS when it could easily do 300 FPS… shame on you! You will lose a lot of visual appeal with this, especially with fast moving objects.

On the other hand, with mobile devices, this can be seen as a benefit. Not letting the game constantly run at it’s edge could save some battery time.

Conclusion

Making the FPS dependent on a constant game speed is a solution that is quickly implemented and keeps the game code simple. But there are some problems: Defining a high FPS will pose problems on slower hardware, and defining a low FPS will waste visual appeal on fast hardware.

Game Speed dependent on Variable FPS

Implementation

Another implementation of a game loop is to let it run as fast as possible, and let the FPS dictate the game speed. The game is updated with the time difference of the previous frame.

    DWORD prev_frame_tick;
    DWORD curr_frame_tick = GetTickCount();

    bool game_is_running = true;
    while( game_is_running ) {
        prev_frame_tick = curr_frame_tick;
        curr_frame_tick = GetTickCount();

        update_game( curr_frame_tick - prev_frame_tick );
        display_game();
    }

The game code becomes a bit more complicated because we now have to consider the time difference in the update_game() function. But still, it’s not that hard.

At first sight this looks like the ideal solution to our problem. I have seen many smart programmers implement this kind of game loop. Some of them probably wished they would have read this article before they implemented their loop. I will show you in a minute that this loop can have serious problems on both slow and fast (yes, FAST!) hardware.

Slow Hardware

Slow hardware can sometimes cause certain delays at some points, where the game gets “heavy”. This can definitely occur with a 3D game, where at a certain time too many polygons get shown. This drop in frame rate will affect the input response time, and therefore also the player’s reaction time. The updating of the game will also feel the delay and the game state will be updated in big time-chunks. As a result the reaction time of the player, and also that of the AI, will slow down and can make a simple maneuver fail, or even impossible. For example, an obstacle that could be avoided with a normal FPS, can become impossible to avoid with a slow FPS. A more serious problem with slow hardware is that when using physics, your simulation can even explode!

Fast Hardware

You are probably wondering how the above game loop can go wrong on fast hardware. Unfortunately, it can, and to show you, let me first explain something about math on a computer.

The memory space of a float or double value is limited, so some values cannot be represented. For example, 0.1 cannot be represented binary, and therefore is rounded when stored in a double. Let me show you using python:

>>> 0.1
0.10000000000000001

This itself is not dramatic, but the consequences are. Let’s say you have a race-car that has a speed of 0.001 units per millisecond. After 10 seconds your race-car will have traveled a distance of 10.0. If you split this calculation up like a game would do, you have the following function using frames per second as input:

>>> def get_distance( fps ):
...     skip_ticks = 1000 / fps
...     total_ticks = 0
...     distance = 0.0
...     speed_per_tick = 0.001
...     while total_ticks < 10000:
...             distance += speed_per_tick * skip_ticks
...             total_ticks += skip_ticks
...     return distance

Now we can calculate the distance at 40 frames per second:

>>> get_distance( 40 )
10.000000000000075

Wait a minute… this is not 10.0??? What happened? Well, because we split up the calculation in 400 additions, a rounding error got big. I wonder what will happen at 100 frames per second…

>>> get_distance( 100 )
9.9999999999998312

What??? The error is even bigger!! Well, because we have more additions at 100 fps, the rounding error has more chance to get big. So the game will differ when running at 40 or 100 frames per second:

>>> get_distance( 40 ) - get_distance( 100 )
2.4336088699783431e-13

You might think that this difference is too small to be seen in the game itself. But the real problem will start when you use this incorrect value to do some more calculations. This way a small error can become big, and fuck up your game at high frame rates. Chances of that happening? Big enough to consider it! I have seen a game that used this kind of game loop, and which indeed gave trouble at high frame rates. After the programmer found out that the problem was hiding in the core of the game, only a lot of code rewriting could fix it.

Conclusion

This kind of game loop may seem very good at first sight, but don’t be fooled. Both slow and fast hardware can cause serious problems for your game. And besides, the implementation of the game update function is harder than when you use a fixed frame rate, so why use it?

Constant Game Speed with Maximum FPS

Implementation

Our first solution, FPS dependent on Constant Game Speed, has a problem when running on slow hardware. Both the game speed and the framerate will drop in that case. A possible solution for this could be to keep updating the game at that rate, but reduce the rendering framerate. This can be done using following game loop:

    const int TICKS_PER_SECOND = 50;
    const int SKIP_TICKS = 1000 / TICKS_PER_SECOND;
    const int MAX_FRAMESKIP = 10;

    DWORD next_game_tick = GetTickCount();
    int loops;

    bool game_is_running = true;
    while( game_is_running ) {

        loops = 0;
        while( GetTickCount() > next_game_tick && loops < MAX_FRAMESKIP) {
            update_game();

            next_game_tick += SKIP_TICKS;
            loops++;
        }

        display_game();
    }

The game will be updated at a steady 50 times per second, and rendering is done as fast as possible. Remark that when rendering is done more than 50 times per second, some subsequent frames will be the same, so actual visual frames will be dispayed at a maximum of 50 frames per second. When running on slow hardware, the framerate can drop until the game update loop will reach MAX_FRAMESKIP. In practice this means that when our render FPS drops below 5 (= FRAMES_PER_SECOND / MAX_FRAMESKIP), the actual game will slow down.

Slow hardware

On slow hardware the frames per second will drop, but the game itself will hopefully run at the normal speed. If the hardware still can’t handle this, the game itself will run slower and the framerate will not be smooth at all.

Fast hardware

The game will have no problems on fast hardware, but like the first solution, you are wasting so many precious clock cycles that can be used for a higher framerate. Finding the balance between a fast update rate and being able to run on slow hardware is crucial.

Conclusion

Using a constant game speed with a maximum FPS is a solution that is easy to implement and keeps the game code simple. But there are still some problems: Defining a high FPS can still pose problems on slow hardware (but not as severe as the first solution), and defining a low FPS will waste visual appeal on fast hardware.

Constant Game Speed independent of Variable FPS

Implementation

Would it be possible to improve the above solution even further to run faster on slow hardware, and be visually more atractive on faster hardware? Well, lucky for us, this is possible. The game state itself doesn’t need to be updated 60 times per second. Player input, AI and the updating of the game state have enough with 25 frames per second. So let’s try to call the update_game() 25 times per second, no more, no less. The rendering, on the other hand, needs to be as fast as the hardware can handle. But a slow frame rate shouldn’t interfere with the updating of the game. The way to achieve this is by using the following game loop:

    const int TICKS_PER_SECOND = 25;
    const int SKIP_TICKS = 1000 / TICKS_PER_SECOND;
    const int MAX_FRAMESKIP = 5;

    DWORD next_game_tick = GetTickCount();
    int loops;
    float interpolation;

    bool game_is_running = true;
    while( game_is_running ) {

        loops = 0;
        while( GetTickCount() > next_game_tick && loops < MAX_FRAMESKIP) {
            update_game();

            next_game_tick += SKIP_TICKS;
            loops++;
        }

        interpolation = float( GetTickCount() + SKIP_TICKS - next_game_tick )
                        / float( SKIP_TICKS );
        display_game( interpolation );
    }

With this kind of game loop, the implementation of update_game() will stay easy. But unfortunately, the display_game() function gets more complex. You will have to implement a prediction function that takes the interpolation as argument. But don’t worry, this isn’t hard, it just takes a bit more work. I’ll explain below how this interpolation and prediction works, but first let me show you why it is needed.

The Need for Interpolation

The gamestate gets updated 25 times per second, so if you don’t use interpolation in your rendering, frames will also be displayed at this speed. Remark that 25 fps isn’t as slow as some people think, movies for example run at 24 frames per second. So 25 fps should be enough for a visually pleasing experience, but for fast moving objects, we can still see a improvement when doing more FPS. So what we can do is make fast movements more smooth in between the frames. And this is where interpolation and a prediction function can provide a solution.

Interpolation and Prediction

Like I said the game code runs on it’s own frames per second, so when you draw/render your frames, it is possible that it’s in between 2 gameticks. Let’s say you have just updated your gamestate for the 10Th time, and now you are going to render the scene. This render will be in between the 10Th and 11Th game update. So it is possible that the render is at about 10.3. The ‘interpolation’ value then holds 0.3. Take this example: I have a car that moves every game tick like this:

    position = position + speed;

If in the 10Th gametick the position is 500, and the speed is 100, then in the 11Th gametick the position will be 600. So where will you place your car when you render it? You could just take the position of the last gametick (in this case 500). But a better way is to predict where the car would be at exact 10.3, and this happens like this:

    view_position = position + (speed * interpolation)

The car will then be rendered at position 530.

So basically the interpolation variable contains the value that is in between the previous gametick and the next one (previous = 0.0, next = 1.0). What you have to do then is make a “prediction” function where the car/camera/… would be placed at the render time. You can base this prediction function on the speed of the object, steering or rotation speed. It doesn’t need to be complicated because we only use it to smooth things out in between the frames. It is indeed possible that an object gets rendered into another object right before a collision gets detected. But like we have seen before, the game is updated 25 frames per second, and so when this happens, the error is only shown for a fraction of a second, hardly noticeable to the human eye.

Slow Hardware

In most cases, update_game() will take far less time than display_game(). In fact, we can assume that even on slow hardware the update_game() function can run 25 times per second. So our game will handle player input and update the game state without much trouble, even if the game will only display 15 frames per second.

Fast Hardware

On fast hardware, the game will still run at a constant pace of 25 times per second, but the updating of the screen will be way faster than this. The interpolation/prediction method will create the visual appeal that the game is actually running at a high frame rate. The good thing is that you kind of cheat with your FPS. Because you don’t update your game state every frame, only the visualization, your game will have a higher FPS than with the second method I described.

Conclusion

Making the game state independent of the FPS seems to be the best implementation for a game loop. However, you will have to implement a prediction function in display_game(), but this isn’t that hard to achieve.

Overall Conclusion

A game loop has more to it than you think. We’ve reviewed 4 possible implementations, and it seems that there is one of them which you should definitely avoid, and that’s the one where a variable FPS dictates the game speed.

A constant frame rate can be a good and simple solution for mobile devices, but when you want to get everything the hardware has got, best use a game loop where the FPS is completely independent of the game speed, using a prediction function for high framerates.

If you don’t want to bother with a prediction function, you can work with a maximum frame rate, but finding the right game update rate for both slow and fast hardware can be tricky.

Now go and start coding that fantastic game you are thinking of!

Koen Witters

Follow me on twitter

If you just want a quick overview of the style, scroll to the bottom of this page and see how some source code was rewritten to my deWiTTERS Style, this should give you an quick idea of how nice it all looks.

Why a Coding Style?

Every programmer uses some sort of style, some good, some terrible. A coding style can give code a uniform look. It can make algorithms more clear or more complex. There are 2 main reasons for a certain coding style:

1. Develop clean and readable code, so when someone else has to dig through it, he can pick it up rather quickly. And more important when you get back to some old code you have written a year ago, you don’t start thinking “I can’t remember being that wasted…”.
2. When working in team, it’s best that everybody uses the same style so the code has a uniform look.

Since I develop most of my code on my own, I don’t have to consider the second reason. And since I am very stuburn, I am not going to take over someone elses style. That’s why my style is completely optimized to produce clean and readable code.

The Basic Rules

I tried to capture the most important aspects of coding style in the following rules.

1. All should be as understandable as possible.
2. All should be as readable as possible, except when it would conflict with the previous rule.
3. All should be as simple as possible, except when it would conflict with the previous rules.

The best way to look at these rules is make everything as simple as possible, unless understandability or readability suffer. Or to quote Albert Einstein:

Make everything as simple as possible, but not simpler.

As a programmer you must always try to respect the above rules, even if you don’t follow my style of coding.

Writing understandable and readable code became possible with the birth of modern programming languages. The days when programming was entirely done in assembly are long past us. Therefore my style tries to be as closely to our natural language as possible. You can almost say my code reads like a book. This is probably also the reason why my code is badly documented. I hardly document at all! I even consider documenting as “bad” (and not in the cool sense of the word). Only when I do something weird I add a comment to explain why. In my humble opinion, comments should never say what your code does, let your code say what it does.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

Martin Fowler

Identifiers

Let’s start with the most important topic of coding style: identifiers. All identifiers and the rest of your code and comments should be written in English. It is not unusual that software projects shift from one person to another, from one company to another one, located at the opposite side of the world. So since you never know where your code is going to be next, write all in English.

Variables

Variable names should be all lowercase with the words separated by underscores. It resembles our natural writing the most and therefore it is the most readable. The underscores just replace the spaces in our normal way of writing. A variable called “RedPushButton” cannot be read as easely and as fast as “red_push_button”, thrust me.

If you want the variables to be understandable, you must give them obvious names. It is clear that variables all represent some kind of “object” or “value”, so name them accordingly. Please don’t waste your time with jkuidsPrefixing vndskaVariables ncqWith ksldjfTheir nmdsadType because it just isn’t understandable or clean. If you have a variable “age” it’s clear that it’s an int or unsigned short. If it is “filename”, well then it must be a string. Easy! Sometimes for some variables it is more understandable if you include the type in it, for example for gui buttons like “play_button” or “cancel_button”.

There are some pre- and postfixes that can increase the readability of your variables. Here follows a list of the most common ones:

is_, has_

Use these for all boolean values so there can be no mistake about their type. It also fits nicely in if statements.

the_

Start all global variables with “the_”, which makes it very clear that there is only one.

_count

Use _count to represent the number of elements. Don’t use plural like “bullets” instead of “bullet_count”, as plural will represent arrays.

Arrays or other variables that represent lists must be written in plural, like enemies, walls and weapons. However, you don’t have to do this for all array types since some arrays don’t really represent a list of items. Some examples of these are “char filename[64]” or “byte buffer[128]“.

Const or Final

Consts or finals must always be written in UPPERCASE, with the words separated by underscores to make them readable, like MAX_CHILDREN, X_PADDING or PI. This use is widespread and should be used to avoid any confusion with normal variables.

You can use MAX and MIN in your constant names to represent value limits.

Types

Types define the classification of variables. It is a rather abstract term, so we cannot use the English language as a reference on how to write them. But we should definitely make an obvious distinction between them and other identifiers. So for types, I use UpperCamelCase. For every class, struct, enum and other things you can put in front of your variable declarations, use UpperCamelCase.

Name your types in such a way that you can use the same name for generic variables, for example:

HelpWindow help_window;
FileHeader file_header;
Weapon weapons[ MAX_WEAPONS ];

Program Flow

if, else if, else

There are a few ways to write if statements. Let’s start with the braces. There are 3 mayor ways to place your braces:

    if(condition)

    if (condition)

    if( condition )

I have never seen an English text where braces are placed like the first example, so why should we code like that? The words are just not properly separated. The second example puts the braces with the condition instead of the if statement, while the braces are actually part of the if statement and not the condition, so the last example is the best. The last one also has the advantage that one has a better overview over the braces structure.

    if (!((age > 12) && (age < 18)))

    if( !((age > 12) && (age < 18)) )

Personally I would write this code differently, but it’s just to show you an example.

Now what to do with the curled braces? Don’t use them! Unfortunately C, C++, Java or C# don’t allow this, only Python does. So we can’t just drop them, but what we can do is place our braces so it looks like a Python program, simple and clean:

    if( condition ) {
        statements;
    }
    else if( condition ) {
        statements;
    }
    else {
        statements;
    }

When conditions get too long, you’ll have to split the line. Try to split it up before an operator and where conditions are leastly related. Align the next line with the previous one and use indentation to reveal the nested structure. Don’t put the curled brace right behind the condition, but in this case put it on the next line to make the subblock clear.

    if( (current_mayor_version < MIN_MAYOR_VERSION)
        || (current_mayor_version == MIN_MAYOR_VERSION
            && current_minor_version < MIN_MINOR_VERSION) )
    {
        update();
    }

When there is only one statement after the if condition, you can skip the curled braces, but make sure you put the statement on the next line, unless it is a return or a break.

    if( bullet_count == 0 )
        reload();

    if( a < 0 ) return;

while

While loops are written the same as if structures. I use 4 spaces for every indentation.

    while( condition ) {
        statements;
    }

For do-while loops, put the while at the same line as the closing bracket. This way there is no confusion if it is a while at the end or the beginning of a subblock.

    do {
        statements;
    } while( condition )

for

for-loops’ one and only purpose in life is iteration. It’s what they do! for-loops can always be replaced with while-loops, but please don’t do that. When you iterate over some elements, try using ‘for’, and if it really doesn’t work out, use a ‘while’. The ‘for’ structure is pretty straight forward:

    for( int i = 0; i < MAX_ELEMENTS; i++ ) {
        statements;
    }

Use i, j, k, l, m for iterating over numbers and ‘it’ for iterating over objects.

switch

Switch statements have a similar structure to if and while structures. The only thing you have to consider is the extra indentation. Also leave an extra space right behind the break.

    switch( variable ) {
        case 0:
            statements;
            break;

        case 1:
            statements;
            break;

        default:
            break;
    }

Functions

Functions do things, and their name should make this clear. Therefore, always include a verb in it, no exceptions! Use the same naming as with variables, this means all lowercase words separated by underscores. This allows you to make nice little sentences in your code that everyone can understand.

Also make sure the function does what the name says it does, no more, no less. So if you have a function called “load_resources”, make sure it only loads resources and doesn’t do any other init stuff. Sometimes you get tempted by quickly initializing things in the load_resources because you already call it from a higher level, but this will only get you into trouble later. My deWiTTERS Style uses very few comments, so a function should definitely do what it’s name says it does. And when a function returns something, make sure it is clear from it’s name what it returns.

Some functions come in “yin and yang” pairs, and you should be consistent with your naming. Some examples are get/set, add/remove, insert/delete, create/destroy, start/stop, increment/decrement, new/old, begin/end, first/last, up/down, next/prev, open/close, load/save, show/hide, enable/disable, resume/suspend, etc.

Here follows a simple function call. Use a space right after the opening brace and right before the closing brace, just as with if structures. Also leaver a space right after the comma, like done in the English language.

    do_something( with, these, parameters );

When function calls get too long, you’ll have to split it up in several lines. Align the next lines with the previous so the structure gets obvious, and break after the comma.

    HWND hwnd = CreateWindow( "MyWin32App", "Cool application",
                              WS_OVERLAPPEDWINDOW,
                              my_x_pos, my_y_pos,
                              my_width, my_height
                              NULL, NULL, hInstance, NULL );

Definition

Here follows an example of a function definition:

    bool do_something_today( with, these, parameters ) {
        get_up();
        go_to( work, car );
        work();
        go_to( home, car );
        sleep();

        return true;
    }

Make sure your functions don’t get too long. Or to quote Linus:

The maximum length of a function is inversely proportional to the complexity and indentation level of that function. So, if you have a conceptually simple function that is just one long (but simple) case-statement, where you have to do lots of small things for a lot of different cases, it’s ok to have a longer function. However, if you have a complex function, and you suspect that a less-than-gifted first-year high-school student might not even understand what the function is all about, you should adhere to the maximum limits all the more closely. Use helper functions with descriptive names (you can ask the compiler to in-line them if you think it’s performance-critical, and it will probably do a better job of it that you would have done).

Classes

For the naming of classes I use the same UpperCamelCase as for types. Don’t bother putting a ‘C’ as a prefix for every class, it’s just a waste of bytes and time.

As for everything, give classes clear and obvious names. So if a class is a child of class “Window”, name it “MainWindow”.

When creating a new class, remember that everything starts from data structures.

Data dominates. If you’ve chosen the right data structures and organized things well, the algorithms will almost always be self-evident. Data structures, not algorithms, are central to programming.

Fred Brooks

Inheritance

“Is a” relationship should be modeled by inheritance, “has a” should be modeled by containment. Make sure you don’t overuse inheritance, it is a great technique, but only when applied properly.

Members

You should definitely make a distinction between members and normal variables. If you don’t do this, you’ll regret it later on. Some possibilities to name them are m_Member or fMember. I prefer to use my_member for non static members and our_member for statics. This way you get nice sentences in you method bodies like

    if( my_help_button.is_pressed() ) {
        our_screen_manager.go_to( HELP_SCREEN );
    }

For the rest everything that applies to variable naming also applies to members. There is one problem that I was unable to fix as of yet, and that is with boolean members. Remember that boolean values must always have “is” or “has” in them. When combining this with “my_” you get crazy stuff like “my_is_old” and “my_has_children”. I haven’t found the perfect solution for this yet, so if you have any suggestions, please leave a comment below this post!

You shouldn’t declare members of a class as public. Sometimes it seems quicker to implement, and therefore better, but oh boy are you wrong (as I was many times before). You should pass through public methods to get to the members of a class.

Methods

Everything that applies to functions also applies to methods, so always include a verb in the name. Make sure you don’t include the name of the class in your method names.

Code Structure

Align similar lines to give your code a better overview, like:

    int object_verts[6][3] = {
        {-100,  0, 100}, {100, 0,  100}, { 100, 0, -100},
        {-100, 11, 100}, (100, 0, -100}, {-100, 0, -100}
    };

    RECT rect;
    rect.left   = x;
    rect.top    = y;
    rect.right  = rect.left  + width;
    rect.bottom = rect.right + height;

Never put multiple statements on the same line unless you have a good reason for it. One or those reason could be that simular lines can be put right after each other for clarity, like:

    if( x & 0xff00 ) { exp -= 16; x >>= 16; }
    if( x & 0x00f0 ) { exp -=  4; x >>=  4; }
    if( x & 0x000c ) { exp -=  2; x >>=  2; }

Related variables of the same type can be declared in a common statement. This makes the code more compact and provides a nicer overview. But never declare unrelated variables in the same statement!

    int x, y;
    int length;

Namespaces, packages

Namespaces or packages should be written in lower case, without any underscores. Use a namespace for every module or layer you write so that the different layers become clear in the code.

Design

When I start a project I don’t do that much upfront design. I just have a global structure in my mind and start coding. Code evolves, whether you like it or not, so give it the chance to evolve.

Evolving code means reworking bad code, and after some programming your code will turn bad. I use following rules to keep a good structure in the code.

1. When a functions gets too big, divide the problem in some smaller helper functions.
2. If a class contains too many members and methods, split a part of the class up in a helper class and include the helper class in your main class (don’t use inheritance for this!). Make sure your helper class doesn’t reference or use the main class for anything.
3. When a module contains too many classes, divide it up into more modules where the higer level module make use of the lower level module.
4. When you are done implementing a feature or fixing a bug, read over the entire files you have changed to make sure everything is in the most perfect state.

Some projects may become big, very big. A way to cope with this increasing complexity is splitting your project up into different layers. In practice, layers are implemented as namespaces. Lower layers are used by the higher layers. So every layer provides functionality to the above, and the topmost provides functionality to the user.

Files

Files should be named after the class they contain. Don’t put more than one class in a file, so you know where to look when you search a specific class. The directory structure should represent the namespaces.

.h file structure

C or C++ header files show the interface of the implementation. This is crucial knowledge when designing the layout of a .h file. In a class, first define the “public” interface that can be used by other classes, then define all “protected” methods and members. This way the most important information for people using the class is shown first. I don’t use private methods or members so all members are grouped at the bottom of the class declaration. This way you have a quick overview of the contents of the class at the bottom. Group the methods together by their meaning.

    /*
     * license header
     */

    #ifndef NAMESPACE_FILENAME_H
    #define NAMESPACE_FILENAME_H

    #include <std>

    #include "others.h"

    namespace dewitters {

        class SomeClass : public Parent {
            public:
                Constructor();
                ~Destructor();

                void public_methods();

            protected:
                void protected_methods();

                int     my_fist_member;
                double  my_second_member;

                const static int MAX_WIDTH;
        };

        extern SomeClass the_some_class;
    }

    #endif

.java .cs file structure

.java or .cs files don’t provide an interface to the class, they just contain the implementation. Since data structures are more important than algorithms, define your members before your methods. This way when you browse through the code, you have a quick impression of the class through its data members. Simular methods should be grouped together.

Here follows a sketchy overview of a .java or .cs file:

    /*
     * license header
     */
    package com.dewitters.example;

    import standard.modules.*;

    import custom.modules.*;

    class SomeClass extends Parent {
        public final int MAX_WIDTH = 100;

        protected int     my_first_member;
        protected double  my_second_member;

        Constructor() {
        }

        Methods() {
        }
    }

Jokes

Some people like to put little jokes in their code, while others hate this kind of funny stuff. In my opinion you can use them as long as the joke doesn’t interfere with the readability of the code or execution of the program.

deWiTTERS Style vs. others

Here I will present you with some live action code. I stole some code from others and rewrote it to my style. Decide for yourself if my style is better or not. In my opinion you can read faster through my code since it is shorter, and all identifiers are carefully named.

If you think you have seen code that can beat the crap out of my style, leave a comment below this post, and I will write it in the most extraordinary ‘deWiTTERS’ style, and post it here.

Indian Hill C Style

/*
 *	skyblue()
 *
 *	Determine if the sky is blue.
 */

int			/* TRUE or FALSE */
skyblue()

{
	extern int hour;

	if (hour < MORNING || hour > EVENING)
		return(FALSE);	/* black */
	else
		return(TRUE);	/* blue */
}

/*
 *	tail(nodep)
 *
 *	Find the last element in the linked list
 *	pointed to by nodep and return a pointer to it.
 */

NODE *			/* pointer to tail of list */
tail(nodep)

NODE *nodep;		/* pointer to head of list */

{
	register NODE *np;	/* current pointer advances to NULL */
	register NODE *lp;	/* last pointer follows np */

	np = lp = nodep;
	while ((np = np->next) != NULL)
		lp = np;
	return(lp);
}

Rewritten to deWiTTERS Style:

bool sky_is_blue() {
    return the_current_hour >= MORNING && the_current_hour <= EVENING;
}

Node* get_tail( Node* head ) {
    Node* tail;
    tail = NULL;

    Node* it;
    for( it = head; it != NULL; it = it->next ) {
        tail = it;
    }

    return tail;
}

“Commenting Code” from Ryan Campbell

/*
 * Summary:     Determine order of attacks, and process each battle
 * Parameters:  Creature object representing attacker
 *              | Creature object representing defender
 * Return:      Boolean indicating successful fight
 * Author:      Ryan Campbell
 */
function beginBattle(attacker, defender) {
    var isAlive;    // Boolean inidicating life or death after attack
    var teamCount;  // Loop counter

    // Check for pre-emptive strike
    if(defender.agility > attacker.agility) {
        isAlive = defender.attack(attacker);
    }

    // Continue original attack if still alive
    if(isAlive) {
        isAlive = attacker.attack(defender);
    }

    // See if any of the defenders teammates wish to counter attack
    for(teamCount = 0; teamCount < defender.team.length; i++) {
        var teammate = defender.team[teamCount];
        if(teammate.counterAttack = 1) {
            isAlive = teammate.attack(attacker);
        }
    }   

    // TODO: Process the logic that handles attacker or defender deaths

    return true;
} // End beginBattle

Rewritten to deWiTTERS Style:

function handle_battle( attacker, defender ) {
    if( defender.agility > attacker.agility ) {
        defender.attack( attacker );
    }

    if( attacker.is_alive() ) {
        attacker.attack( defender );
    }

    var i;
    for( i = 0; i < defender.get_team().length; i++ ) {
        var teammate = defender.get_team()[ i ];
        if( teammate.has_counterattack() ) {
            teammate.attack( attacker );
        }
    }

    // TODO: Process the logic that handles attacker or defender deaths
}

Koen Witters

Follow me on twitter