linktree Atrinik.org - Multiplayer Online Role Playing Game
Programming Guide
Development -> Programming GuideHints for new coders

1) Variable abbreviations: op is short for object pointer, ob is for object, and pl is for player.

2) Some functions are named using the conventions above - the naming reflects what options they take (insert_ob_in_ob takes 2 object structures).

3) Indentation is one tab, but spaces for formatting.

4) Some structure elements should never be accessed directly - rather, there are other functions to use the values.

object->owner:  This contains the owner id for this object.  Use set_owner and get_owner instead. Directly using object->owner is likely to get unpredictable results.

object->nrof:  This contains the number of an object. Since changing this will change the weight of an object, direct access should also be avoided. Use decrease_ob_nr, split_ob and insert_ob_in_... - the later will merge the objects if applicable.

5) If using insert_ob_in_map and plan to do further actions with the object, check and make sure the object still exists after insertion - it is possible that the object gets destroyed while being inserted.

Style guide for new additions

1) Use descriptive variable names. op and pl should only be used for temporary variables (cycling through the list or the like). For variables well defined, use an accurate name (ie, hitter, sack, etc).

2) Only add name options with #ifdef's to the config.h file if the behavior seriously changes the game. Adding a new spell does not warrant an #ifdef. There are already too many options in the config.h file.

3) Log errors/diagnostics with the LOG function. When doing so, please include the function name - this is especially true for errors.

4) If you want to add special debug code for certain compiles, generate a unique #define for it - don't use the global DEBUG. For example, NEWCS_DEBUG.

5) Try to use the [s/u]int[8/16/32/64] whenever possible. Use the one of appropriate size/type. If not sure, go for the next size up. Do not ever write code assuming that any of those will have an exact number of bits - those types only mean that you will get at least that many bits - you may get more.

6) The exception to #5 above is strings. Continue to use 'char', since the signedness of functions that take string options can differ system to system, and generate excessive warnings if the wrong sign is used.

7) When adding new function, include a comment of what the function is supposed to do, what options it takes, and what if any value it returns. This makes debugging of such functions easier, and also makes it better known to other developers if that function might be useful to them. All such comments should be in Doxygen style.

8) Don't use nonstandard GCC extensions (// for comment lines, ability to nest functions, declare arrays with variable bounds, etc). Likewise, don't use special system functions - don't assume the target system will be bsd or svr4 - if using a potentially non standard function, add checks in the autoconf script and include a version of the function in case it is not on that system. The key word here is portability - don't assume everyone else has the same system as you do.

9) Write code that can easily be maintained in the future, not code that is easiest to write at that second. This basically means don't do the quick and ugly hack, but instead fix it properly.

10)
/* Do block
 * comment like
 * this */

/*
  And not
  like this
*/

/* If you are doing a single line comment, this method is fine */

It's much easier to spot the block comments if they all start with *, and these comments tend to be worth noticing.

11) The preferred style for expressions is like this:

if (expression)
{
   statement;
   statement;
}

if (expression), the space between the if and expression is required.

NOT like this:
if (expression) {
   statement;
   statement;
}

12) The preferred style of function parameters:
void myFunction(char *param1, int param2, object *param3)
{
   statement;
   statement;
}

13) Local variable names.

These are okay:
   int mylongvarname;
   int my_long_var_name;

Please do NOT use caps expect for typedefs, enums and defines.

14) All code should compile without any warnings. The default Makefiles will prevent compilation for code that contains warnings, by turning the warnings into errors.

Sending in patches

1) Please send patches on a bug fix or feature enhancement basis individually, and not make mega patches. A diff that changes 10 things is first more difficult for us to look over and understand as unrelated changes might be going on. It is also more difficult for us to reject part of a patch (feature X is nice, but Y doesn't work).

2) Please state in the message included with the patch what it fixes/changes.

3) When making patches, please make context diffs. Please also include the directory that the file is in (run the diff in the top level directory). Please make 5 line context diffs - large line context diffs are fine if you think that may make it easier.

Example:
Quote
diff -c5 (oldfile) (newfile)


You can also do diffs of entire directories.  Do do this, type:
Quote
diff -c5 -r (old_directory) (new_directory)


If you're working on a local copy of Bazaar checkout/branch, you can use this (and check the options by reading 'bzr help diff'):
Quote
bzr diff


4) GNU diff will include files that did not exist before. Other diff programs may not do this.

5) There is no need to make a separate diff file for each file different (ie, treasure.diff, player.diff, etc). Assuming you follow the above steps, all the diffs can be contained in one file, and patch will deal with it just fine.

6) If you need to send a map, new archetypes, or other new files where a diff doesn't make sense, a gzipped tar file will work just fine.

Mail all patches to atrinik-dev@lists.launchpad.net (note that the email address you're emailing from must be registered with Launchpad), or if your changes are big ones, make a branch by clicking the "Submit code" link here once you're logged in. By submitting new graphics, maps, stories, etc to the Atrinik project you agree for them to be placed under GNU GPLv2.

You can also join the Atrinik Developer Team, or subscribe to the developer mailing list by going here.