| 1 |
I've redone this file to hopefully make it a little easier to read through
|
| 2 |
and quickly get some idea what to do. There are 3 sections -
|
| 3 |
section 1 is current programming style/hints for developers to make
|
| 4 |
things easier. Section 2 is programming guide for new addition.
|
| 5 |
Section 3 is notes for making patches.
|
| 6 |
|
| 7 |
------------------------------------------------------------------------------
|
| 8 |
Section 1 - currently used conventions/hints for new code writers:
|
| 9 |
|
| 10 |
1) variable abbreviations - op is short for object pointer, ob is for
|
| 11 |
object, and pl is for player.
|
| 12 |
|
| 13 |
2) Some functions are named using the conventions above - the naming reflects
|
| 14 |
what options they take (insert_ob_in_ob takes 2 object structures)
|
| 15 |
|
| 16 |
3) Identation is either 2 spaces or 4 spaces. This can be a pain
|
| 17 |
to read, but most functions should be consistent through the function.
|
| 18 |
|
| 19 |
4) Some structure elements should never be accessed directly - rather,
|
| 20 |
there are other functions to use the values.
|
| 21 |
|
| 22 |
object->owner: This contains the owner id for this object. Use
|
| 23 |
set_owner and get_owner instead. Directly using object->owner
|
| 24 |
is likely to get unpredictable results.
|
| 25 |
|
| 26 |
object->nrof: This contains the number of an object.
|
| 27 |
Since changing this will change the weight of an object, direct
|
| 28 |
access should also be avoided. Use decrease_ob_nr, split_ob,
|
| 29 |
and insert_ob_in_... - the later will merge the objects if
|
| 30 |
applicable.
|
| 31 |
|
| 32 |
5) If using insert_ob_in_map and plan to do further actions with the object,
|
| 33 |
check and make sure the object still exists after insertion - it is possible
|
| 34 |
that the object gets destroyed while being inserted.
|
| 35 |
|
| 36 |
------------------------------------------------------------------------------
|
| 37 |
Section 2 - Style guide for new additions:
|
| 38 |
|
| 39 |
1) Use descriptive variable names. op and pl should only be used for
|
| 40 |
temporary variables (cycling through the list or the like). For variables
|
| 41 |
well defined, use an accurate name (ie, hitter, sack, etc).
|
| 42 |
|
| 43 |
2) Only add name options with #ifdef's to the config file if the behaviour
|
| 44 |
seriously changes the game. Adding a new spell does not warrant an
|
| 45 |
#ifdef. There are already too many options in the config.h file.
|
| 46 |
|
| 47 |
3) Log errors/diagnostics with the LOG function. When doing so,
|
| 48 |
please include the function name - this is especially true for errors.
|
| 49 |
|
| 50 |
4) If you want to add special debug code for certain compiles, generate
|
| 51 |
a unique #define for it - don't use the global DEBUG. For example,
|
| 52 |
NEWCS_DEBUG.
|
| 53 |
|
| 54 |
5) Try to use the [s/u]int[8/16/32] whenever possible. Use the one
|
| 55 |
of appropriate size/type. If not sure, go for the next size up. Do
|
| 56 |
not ever write code assuming that any of those will have an exact number
|
| 57 |
of bits - those types only mean that you will get at least that many
|
| 58 |
bits - you may get more.
|
| 59 |
|
| 60 |
6) The exception to #5 above is strings. Continue to use 'char', since
|
| 61 |
the signedness of functions that take string options can differ system
|
| 62 |
to system, and generate excessive warnings if the wrong sign is used.
|
| 63 |
|
| 64 |
7) When adding new function, include a comment of what the function is
|
| 65 |
supposed to do, what options it takes, and what if any value it returns.
|
| 66 |
This makes debugging of such functions easier, and also makes it better
|
| 67 |
known to other developers if that function might be useful to them.
|
| 68 |
|
| 69 |
8) Try to keep lines to less than 80 columns when possible. This is not
|
| 70 |
a strict requirement - don't break up some complex comparison because the
|
| 71 |
line would otherwise be 83 characters long. Xterms can be resized to most
|
| 72 |
any width. However, use your judgement on whether breaking up a long
|
| 73 |
line would make something more or less readable.
|
| 74 |
|
| 75 |
9) Assume all names use one namespace. For example, if there is a
|
| 76 |
struct called spell, don't make the name of an optional parameter spell.
|
| 77 |
This will break on ANSI C compilers that follow the spec strictly
|
| 78 |
(gcc does not, even with -strict -ansi)
|
| 79 |
|
| 80 |
10) As a followup on 9 above, don't use nonstandard gcc extensions
|
| 81 |
(// for comment lines, ability to nest functions, declare arrays with
|
| 82 |
variable bounds, etc.) Likewise, don't use special system functions - don't
|
| 83 |
assume the target system will be bsd or svr4 - if using a potentially non
|
| 84 |
standard function, add checks in the autoconf script and include a version
|
| 85 |
of the function in case it is not on that system. They key word here is
|
| 86 |
portability - don't assume everyone else has the same system as you do.
|
| 87 |
|
| 88 |
11) Write code that can easily be maintained in the future, not code that
|
| 89 |
is easiest to write at that second. This basically means don't do the
|
| 90 |
quick and ugly hack, but instead fix it properly.
|
| 91 |
|
| 92 |
12) Use 4 space indentation. While a lot of old code may have 2 space,
|
| 93 |
the move to 4 space will make future readability easier.
|
| 94 |
|
| 95 |
13)
|
| 96 |
/*
|
| 97 |
* do block
|
| 98 |
* comment like
|
| 99 |
* this
|
| 100 |
*/
|
| 101 |
|
| 102 |
/*
|
| 103 |
and not
|
| 104 |
like this
|
| 105 |
*/
|
| 106 |
|
| 107 |
/* if you are doing a single line comment, this method is fine */
|
| 108 |
|
| 109 |
Its much easier to spot the block comments if they all start with *,
|
| 110 |
and these comments tend to be worth noticing.
|
| 111 |
|
| 112 |
14) As discussed on irc, the preferred style for expressions is like this:
|
| 113 |
|
| 114 |
if (expression) {
|
| 115 |
statement;
|
| 116 |
statement;
|
| 117 |
}
|
| 118 |
|
| 119 |
if <space> (expression), the space between the if and expression is required.
|
| 120 |
|
| 121 |
NOT like this:
|
| 122 |
|
| 123 |
if (expression)
|
| 124 |
{
|
| 125 |
statement;
|
| 126 |
statement;
|
| 127 |
}
|
| 128 |
|
| 129 |
15) The preferred style of formal parameters:
|
| 130 |
|
| 131 |
void myFooFunction(param1, param2, param3) {
|
| 132 |
statement;
|
| 133 |
statement;
|
| 134 |
}
|
| 135 |
|
| 136 |
No space after the left paren, no space before the right paren.
|
| 137 |
Comma right after the formal param, space right after the comma.
|
| 138 |
|
| 139 |
|
| 140 |
16) Local variable names. Just a rules of thumb.
|
| 141 |
|
| 142 |
This are ok:
|
| 143 |
|
| 144 |
int mylongvarname;
|
| 145 |
int my_long_var_name;
|
| 146 |
|
| 147 |
Please do NOT use caps expect for typedefs, enums and defines.
|
| 148 |
|
| 149 |
------------------------------------------------------------------------------
|
| 150 |
Section 3 - sending in patches:
|
| 151 |
|
| 152 |
1) Please send patches on a bug fix or feature enhancement basis
|
| 153 |
individually, and not make mega patches. A diff that changes 10
|
| 154 |
things is first more difficult for me to look over and understand as
|
| 155 |
unrelated changes might be going on. It is also harder for me to reject
|
| 156 |
part of a patch (feature X is nice, but Y doesn't work).
|
| 157 |
|
| 158 |
2) Please state in the message included with the patch what it fixes/changes.
|
| 159 |
Too often, I get patches which is just a bunch of source code, and I have
|
| 160 |
no idea if I want to incorporate it, or even if the bug is still there.
|
| 161 |
Please also state what version of crossfire the diff is for.
|
| 162 |
|
| 163 |
3) I will assume any patches mailed directly to me are to be included.
|
| 164 |
If posting a patch on the mailing list (either source or ftp location),
|
| 165 |
please explicity state whether or not you want that patch incorporated
|
| 166 |
into the master source. Many times, a patch may be made available on
|
| 167 |
an expiremental basis which is not ready for widespread distribution.
|
| 168 |
|
| 169 |
4) When making patches, please make context diffs. Please also include
|
| 170 |
the directory that the file is in (run the diff in the top level
|
| 171 |
directory). Please make 5 line context diffs - large line context diffs
|
| 172 |
are fine if you think that may make it easier.
|
| 173 |
|
| 174 |
Example:
|
| 175 |
|
| 176 |
'diff -c5 (oldfile) (newfile)'
|
| 177 |
|
| 178 |
You can also do diffs of entire directories. Do do this, type:
|
| 179 |
|
| 180 |
'diff -c5 -r (old_directory) (new_directory)'
|
| 181 |
|
| 182 |
An example:
|
| 183 |
|
| 184 |
'diff -c5 -r crossfire-0.90.1 crossfire-0.90.2'
|
| 185 |
|
| 186 |
5) Gnu diff will include files that did not exist before. Other diff
|
| 187 |
programs may not do this.
|
| 188 |
|
| 189 |
6) If your diff looks excessively long and you made a lot of formatting
|
| 190 |
changes, you can add -w to the diff options to have it ignore whitespace.
|
| 191 |
Note that this will then mean that those formatting changes will then be lost.
|
| 192 |
|
| 193 |
7) There is no need to make a seperate diff file for each file
|
| 194 |
different (ie, treasure.diff, player.diff, etc). Assuming you follow steps
|
| 195 |
1-6, all the diffs can be contained in one file, and patch will deal with
|
| 196 |
it just fine.
|
| 197 |
|
| 198 |
8) If you need to send a map, new archetypes, or other new files where
|
| 199 |
a diff doesn't make since, a uuencoded tar file will work just fine.
|
| 200 |
|
| 201 |
Submit all patches to the Sourceforge patch tracker on
|
| 202 |
http://sourceforge.net/projects/crossfire., and mail an announcement to
|
| 203 |
crossfire-devel@lists.real-time.com.
|
| 204 |
|
| 205 |
|
