1 |
root |
1.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 |
|
|
|