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 |
Take from http://www.jwz.org/doc/tabs-vs-spaces.html |
96 |
|
97 |
In Emacs, to set the mod-N indentation used when you hit the TAB key, do this: |
98 |
|
99 |
(setq c-basic-indent 2) |
100 |
or (setq c-basic-indent 4) |
101 |
|
102 |
To cause the TAB file-character to be interpreted as mod-N indentation, do this: |
103 |
|
104 |
(setq tab-width 4) |
105 |
or (setq tab-width 8) |
106 |
|
107 |
To cause TAB characters to not be used in the file for compression, and for only |
108 |
spaces to be used, do this: |
109 |
|
110 |
(setq indent-tabs-mode nil) |
111 |
|
112 |
To keep myself honest (that is, to ensure that no tabs ever end up in source |
113 |
files that I am editing) I also do this in my .emacs file: |
114 |
|
115 |
(defun java-mode-untabify () |
116 |
(save-excursion |
117 |
(goto-char (point-min)) |
118 |
(while (re-search-forward "[ \t]+$" nil t) |
119 |
(delete-region (match-beginning 0) (match-end 0))) |
120 |
(goto-char (point-min)) |
121 |
(if (search-forward "\t" nil t) |
122 |
(untabify (1- (point)) (point-max)))) |
123 |
nil) |
124 |
|
125 |
(add-hook 'java-mode-hook |
126 |
'(lambda () |
127 |
(make-local-variable 'write-contents-hooks) |
128 |
(add-hook 'write-contents-hooks 'java-mode-untabify))) |
129 |
|
130 |
That ensures that, even if I happened to insert a literal tab in the file by |
131 |
hand (or if someone else did when editing this file earlier), those tabs get |
132 |
expanded to spaces when I save. This assumes that you never use tabs in places |
133 |
where they are actually significant, like in string or character constants, but |
134 |
I never do that: when it matters that it is a tab, I always use '\t' instead. |
135 |
|
136 |
To get vim to interpret tab as an ``indent'' command instead of an insert-a-tab |
137 |
command, do this: |
138 |
|
139 |
set softtabstop=2 |
140 |
|
141 |
To set the mod-N indentation used when you hit the tab key in vim (what Emacs |
142 |
calls c-basic-indent), do this: |
143 |
|
144 |
set shiftwidth=2 |
145 |
|
146 |
To cause the TAB file-character to be displayed as mod-N in vi and vim (what |
147 |
Emacs calls tab-width), do this: |
148 |
|
149 |
set tabstop=4 |
150 |
|
151 |
To cause TAB characters to not be used in the file for compression, and for only |
152 |
spaces to be used (what emacs calls indent-tabs-mode), do this: |
153 |
|
154 |
set expandtab |
155 |
|
156 |
12.1) I work on several projects and each uses a different indent format. What |
157 |
do I do? |
158 |
|
159 |
Taken from an email from Eric Estabrooks <estabroo@talkware.net>, which is |
160 |
based on info found in the linux kernel. |
161 |
|
162 |
add to your .emacs |
163 |
; linux kernel c mode |
164 |
(defun linux-c-mode () |
165 |
"C mode with adjusted defaults for use with the Linux kernel." |
166 |
(interactive) |
167 |
(c-mode) |
168 |
(c-set-style "K&R") |
169 |
(setq c-basic-offset 8)) |
170 |
|
171 |
; set linux kernel mode for anything in /usr/src/linux* |
172 |
(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode) |
173 |
auto-mode-alist)) |
174 |
|
175 |
13) |
176 |
/* |
177 |
* do block |
178 |
* comment like |
179 |
* this |
180 |
*/ |
181 |
|
182 |
/* |
183 |
and not |
184 |
like this |
185 |
*/ |
186 |
|
187 |
/* if you are doing a single line comment, this method is fine */ |
188 |
|
189 |
Its much easier to spot the block comments if they all start with *, |
190 |
and these comments tend to be worth noticing. |
191 |
|
192 |
14) As discussed on irc, the preferred style for expressions is like this: |
193 |
|
194 |
if (expression) { |
195 |
statement; |
196 |
statement; |
197 |
} |
198 |
|
199 |
if <space> (expression), the space between the if and expression is required. |
200 |
|
201 |
NOT like this: |
202 |
|
203 |
if (expression) |
204 |
{ |
205 |
statement; |
206 |
statement; |
207 |
} |
208 |
|
209 |
15) The preferred style of formal parameters: |
210 |
|
211 |
void myFooFunction(param1, param2, param3) { |
212 |
statement; |
213 |
statement; |
214 |
} |
215 |
|
216 |
No space after the left paren, no space before the right paren. |
217 |
Comma right after the formal param, space right after the comma. |
218 |
|
219 |
|
220 |
16) Local variable names. Just a rules of thumb. |
221 |
|
222 |
This are ok: |
223 |
|
224 |
int mylongvarname; |
225 |
int my_long_var_name; |
226 |
|
227 |
Please do NOT use caps expect for typedefs, enums and defines. |
228 |
|
229 |
------------------------------------------------------------------------------ |
230 |
Section 3 - sending in patches: |
231 |
|
232 |
1) Please send patches on a bug fix or feature enhancement basis |
233 |
individually, and not make mega patches. A diff that changes 10 |
234 |
things is first more difficult for me to look over and understand as |
235 |
unrelated changes might be going on. It is also harder for me to reject |
236 |
part of a patch (feature X is nice, but Y doesn't work). |
237 |
|
238 |
2) Please state in the message included with the patch what it fixes/changes. |
239 |
Too often, I get patches which is just a bunch of source code, and I have |
240 |
no idea if I want to incorporate it, or even if the bug is still there. |
241 |
Please also state what version of crossfire the diff is for. |
242 |
|
243 |
3) I will assume any patches mailed directly to me are to be included. |
244 |
If posting a patch on the mailing list (either source or ftp location), |
245 |
please explicity state whether or not you want that patch incorporated |
246 |
into the master source. Many times, a patch may be made available on |
247 |
an expiremental basis which is not ready for widespread distribution. |
248 |
|
249 |
4) When making patches, please make context diffs. Please also include |
250 |
the directory that the file is in (run the diff in the top level |
251 |
directory). Please make 5 line context diffs - large line context diffs |
252 |
are fine if you think that may make it easier. |
253 |
|
254 |
Example: |
255 |
|
256 |
'diff -c5 (oldfile) (newfile)' |
257 |
|
258 |
You can also do diffs of entire directories. Do do this, type: |
259 |
|
260 |
'diff -c5 -r (old_directory) (new_directory)' |
261 |
|
262 |
An example: |
263 |
|
264 |
'diff -c5 -r crossfire-0.90.1 crossfire-0.90.2' |
265 |
|
266 |
5) Gnu diff will include files that did not exist before. Other diff |
267 |
programs may not do this. |
268 |
|
269 |
6) If your diff looks excessively long and you made a lot of formatting |
270 |
changes, you can add -w to the diff options to have it ignore whitespace. |
271 |
Note that this will then mean that those formatting changes will then be lost. |
272 |
|
273 |
7) There is no need to make a seperate diff file for each file |
274 |
different (ie, treasure.diff, player.diff, etc). Assuming you follow steps |
275 |
1-6, all the diffs can be contained in one file, and patch will deal with |
276 |
it just fine. |
277 |
|
278 |
8) If you need to send a map, new archetypes, or other new files where |
279 |
a diff doesn't make since, a uuencoded tar file will work just fine. |
280 |
|
281 |
Mail all patches to crossfire-devel@lists.real-time.com |
282 |
|