HackingWesnoth

This page is designed to be a guide for aspiring Wesnoth programmers on what they need to do to be able to productively contribute to the Wesnoth code base.

Wesnoth is written in C++, a large and complicated language. There are many C++ programmers, but they tend to have widely varying levels of skills and styles. This page is designed to be a guide as to the skillset needed to contribute to Wesnoth.

C++ Quiz

Below is a short C++ quiz that assesses your skills in areas of C++ that are used alot in Wesnoth. If you know all the answers to the questions, you are probably ready to start working on the Wesnoth code base. If you know most of the answers to the questions, you can probably work on the Wesnoth code base with some oversight from the senior developers.

(1) What is a virtual destructor? Why is it needed?

(2) What does the standard class template auto_ptr do? What is its purpose?

(3) What is a vector, and why would you use it?

(4) What is a map, and why would you use it?

(5) What are the differences between a reference and a pointer? When should each be used?

(6) What is an iterator, and when is it used?

(7) What are the memory areas in a C++ program, and what is the purpose of each?

(8) What is a copy constructor, and what is an assignment operator? When must you define them in a class?

Wesnoth Coding Style

Guideline 1: Don't prematurely optimize

When I was a new and inexperienced coder, I read the following rather famous saying: "Premature optimization is the root of all evil." -- Donald Knuth.

While I wouldn't then -- and would be hesitant to now -- dispute the opinion of Donald Knuth on any programming topic, this absolute statement confused me. Premature optimization certainly doesn't sound like a wise thing to do, but it sounds somewhat obscure to be the root of all problems in programming. Had Knuth written this phrase after spending too long correcting problems caused by a programmer who was hell-bent on optimization at every turn?

Now I realize that Knuth was correct. Time and time again programming problems spring from developers making their code too complicated because they are trying to optimize unnecessarily.

By the Pareto Principle we know that a minority of the code will occupy a majority of the running time. That is, perhaps 90% of the running time of the program will be spend executing just 5% of the code. It is thus generally unnecessary to apply many optimizations at all to most of the program. One can just write the code in a way that is the most readable and maintainable and forget about optimization altogether most of the time.

Remember also, C++ compilers are good, and smart, and they can execute code fast. Most code will run fast enough, unless you go out of your way to make it run slowly.

So, the first rule of Wesnoth programming is that unless you have a very good reason to think you need to optimize, do whatever is simplest and most maintainable.

Many programmers seem to have an obsession with using the control C++ gives them to do all sorts of crazy things. Like make their own memory management routines, or write their own containers, and so forth. Simply, don't. It's possible to write good C++ code very fast using the standard components supplied as part of the language.

This leads us to our next topic...

Guideline 2: Know the Standard containers and use them

One of the best things about C++ is that the standard supplies some great containers. Always prefer to use them first to store data. That is,

- prefer to use std::vector to store dynamic arrays - prefer to use std::string to store strings (we also provide t_string for a translatable string -- it's based on std::basic_string, which std::string is also based on) - prefer to use std::map to store key/value pairs - prefer to use std::set to store sets of items (roughly equivalent to the mathematical concept of a set).

There are other C++ containers, and you should know about all of them. A good source of documentation on the portion of the C++ standard library known as the Standard Template Library (STL) which contains the standard containers can be found here.

By using the standard containers, you should almost never have to manually allocate and delete memory yourself by hand. The containers will automatically allocate and deallocate memory for you. This leads us to our next guideline...

Guideline 3: Use the resource acquisition is initialization (RAII) idiom

In C, you might write some code like this:

void myfunction()
{
    char* mystring = (char*)malloc(n);
    /*some code, which manipulates mystring*/
    ...
    free(mystring);
}

This code works, but is error prone. What if the code in the middle exited using a return statement, or a longjmp statement, or in C++, threw an exception? The memory allocated would never be cleaned up, and we would have a memory leak.

Sure, you're a good programmer, and you probably make sure you're very careful about freeing the string. But what about when this function grows to be 100 lines long (and functions have a way of doing that), and then another programmer who isn't that familiar with the function is trying to fix a critical bug as quickly as they can, that requires adding an early return statement to this function? What about when someone is trying to read the code to scan for memory leaks? Once they see the malloc at the top, they will have to carefully read the entire function, to make sure it's all okay.

Now if we had this C++ version instead,

void myfunction()
{
    std::string mystring(n,'x');
    /*some code, which manipulates mystring*/
} //mystring is destroyed and memory automatically released

None of these problems can possibly happen. mystring will always be released at the end of the function.

So, this just re-iterates how important C++ containers are, right? Well, yes, but it also shows us that we should always avoid code written like this:

void myfunction()
{
    ...allocate resources...
    ...use resources
    ...release resources...
}

If you have code like this, you should put the resources in a class that will manage them and release them at the end of the function. If there is no class like that, then you should write one. This goes for all resources: memory, files, threads, and so forth.

It might sound like a silly mistake that we're protecting against here, one that an experienced programmer wouldn't make. However, almost all programming bugs are due to 'silly mistakes'. This leads us to our next item...

Guideline 4: Lean on the compiler as heavily as you can

Humans make mistakes. Even very stupid mistakes. Computers are as dumb as toast, but they are at least very very consistent.

For Wesnoth, we try to write code that will make the compiler guard against mistakes as much as possible. The use of RAII as described above is one example of this: writing the code so the compiler and language rules will guarantee it's correct.

There are some more ways to do this. One big way is to make all code const correct. That is, always define something as 'const' when it shouldn't change its value. If you have a pointer that is meant to be read only, define it as a const pointer. Then if the code is later changed so that your pointer changes the value, the compiler will produce an error.

Another way is to avoid implicit conversions between objects, and always use the C++-style casts.