New Contributors Guide C Code

C++ Contributions

CDDA is written almost entirely in C++. New contributions that change the C++ files are as welcome as changes to the JSON files, but they are more complicated and its harder to provide guidance.

What is C++ ?

So first off, this is not a guide to learning programming in general or C++ programming in particular. I am a professional programmer with a decade of formal education and a quarter century of paid experience and I don't know what to tell you about learning how to program. If you need an answer to what C++ is, please go back to the front of the guide and learn about contributing in JSON, or do some searches on google.

Contributing with C++

Assuming you know how to program a little, and have some vague understanding of C++, you can contribute to CDDA. You'll need to set up a github account and you should know some git basics if you don't already.

There is a guide to compiling that is fairly decent. Beyond that, the process is basically the same:

1. Fork and clone repo and checkout a working branch.
2. Write code.
3. Test your code.
4. Make a PR.
5. Respond to reviews.

The CDDA codebase is fairly large. There is a rough overview of the code structure but the codebase is very large and constantly changing, so the overview is approximate and possibly outdated. I probably can't answer your question about how any specific part of it works. Use git grep, find something that looks like it might be suitable, and read out from there. Header files are usually (but not always) well-documented.

C++ contributions usually get more scrutiny that JSON contributions. Be prepared to make changes to your code or defend your design. People are still friendly and will try to help, but requiring good code is the only way to maintain a project the size of CDDA.

Advice on C++ Contributions

Adding new data from JSON

When writing new code that adds new data, if at all possible, try to make that data accessible from JSON instead of hardcoding the values into the source code. This will speed up your programming, since you'll be able to make minor adjustments without recompiling, and makes other contributors and modders happy, since they can also adjust things without needing to understand the C++ code.

CDDA provides standard APIs for reading JSON data. These are normally called "factories". Various entities in the game already have their own factories (such as monster factory or item factory), but there is also a generic factory API in src/generic_factory.h that is preferred for new JSON data.

Implementing a generic factory is pretty simple:

• include "generic_factory.h" and "json.h" in the file defining your class or strucuture
• declare a void load( const JsonObject &jo, const std::string &src ); member function
• • define the load() function to read the JSON into your class of structure
• • use the standard mandatory() or optional() functions for mandatory or optional fields, respectively
• declare a void check() const; member function
• • define the check() function to do any post-loading sanity checks on your class or structure

src/magic.cpp has an excellent example of how this works in spell_type::load()