[Crossfire-wiki] [Crossfire DokuWiki] page changed: coding_style_guide

no-reply_wiki at metalforge.org no-reply_wiki at metalforge.org
Thu Jun 15 12:24:31 CDT 2006


A page in your DokuWiki was added or changed. Here are the details:



Date        : 2006/06/15 17:24

User        : 

Edit Summary: Partially wikified, not done yet



@@ -1,104 +1,33 @@

- The following is a mirror of //crossfire/doc/Developers/programming_guid
e// from the server source.

+ The following is a wikified mirror of //crossfire/doc/Developers/program
ming_guide// from the server source.

  

  ----

  

- I've redone this file to hopefully make it a little easier to read throu
gh

- and quickly get some idea what to do.  There are 3 sections - 

- section 1 is current programming style/hints for developers to make

- things easier.  Section 2 is programming guide for new addition.

- Section 3 is notes for making patches.

+ ====== Section 1 - currently used conventions/hints for new 
code writers: ======

  

- ------------------------------------------------------------------------
------

- Section 1 - currently used conventions/hints for new code writers:

+   - variable abbreviations - op is short for object pointer, ob is for o
bject, and pl is for player.

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

+   - Identation is either 2 spaces or 4 spaces.  This can be a pain to re
ad, but most functions should be consistent through the function.

+   - 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 s
et_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 changi
ng 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 w
ill merge the objects if applicable.

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

  

- 1) variable abbreviations - op is short for object pointer, ob is for

- object, and pl is for player.

+ ====== Section 2 - Style guide for new additions: ===
===

  

- 2) Some functions are named using the conventions above - the naming ref
lects

- what options they take (insert_ob_in_ob takes 2 object structures)

- 

- 3) Identation is either 2 spaces or 4 spaces.  This can be a pain

- to read, but most functions should be consistent through the function.

- 

- 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 obj
ect,

- check and make sure the object still exists after insertion - it is poss
ible

- that the object gets destroyed while being inserted.

- 

- ------------------------------------------------------------------------
------

- Section 2 - 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 variabl
es

- well defined, use an accurate name (ie, hitter, sack, etc).

- 

- 2) Only add name options with #ifdef's to the config file if the behavio
ur

- 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] 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.

- 

- 8) Try to keep lines to less than 80 columns when possible.  This is not

- a strict requirement - don't break up some complex comparison because th
e

- line would otherwise be 83 characters long.  Xterms can be resized to mo
st

- any width.  However, use your judgement on whether breaking up a long

- line would make something more or less readable.

- 

- 9) Assume all names use one namespace.  For example, if there is a

- struct called spell, don't make the name of an optional parameter spell.

- This will break on ANSI C compilers that follow the spec strictly

- (gcc does not, even with -strict -ansi)

- 

- 10) As a followup on 9 above, 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 - d
on't

- assume the target system will be bsd or svr4 - if using a potentially no
n

- standard function, add checks in the autoconf script and include a versi
on

- of the function in case it is not on that system.  They key word here is

- portability - don't assume everyone else has the same system as you do.

- 

- 11) Write code that can easily be maintained in the future, not code tha
t

- is easiest to write at that second.  This basically means don't do the

- quick and ugly hack, but instead fix it properly.

- 

- 12) Use 4 space indentation.  While a lot of old code may have 2 space,

- the move to 4 space will make future readability easier.

- 

- 13)

-  /*

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

+   - Only add name options with #ifdef's to the config file if the behavi
our seriously changes the game.  Adding a new spell does not warrant an #i
fdef. There are already too many options in the config.h file.

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

+   - 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.

+   - Try to use the [s/u]int[8/16/32] 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.

+   - 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.

+   - 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. T
his makes debugging of such functions easier, and also makes it better kno
wn to other developers if that function might be useful to them.

+   - Try to keep lines to less than 80 columns when possible.  This is no
t a strict requirement - don't break up some complex comparison because th
e line would otherwise be 83 characters long.  Xterms can be resized to mo
st any width.  However, use your judgement on whether breaking up a long l
ine would make something more or less readable.

+   - Assume all names use one namespace.  For example, if there is a stru
ct called spell, don't make the name of an optional parameter spell. This 
will break on ANSI C compilers that follow the spec strictly (gcc does not
, even with -strict -ansi)

+   - As a followup on 9 above, don't use nonstandard gcc extensions (// f
or 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 standa
rd function, add checks in the autoconf script and include a version of th
e function in case it is not on that system.  They key word here is portab
ility - don't assume everyone else has the same system as you do.

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

+   - Use 4 space indentation.  While a lot of old code may have 2 space, 
the move to 4 space will make future readability easier.

+   - <code>/*

    * do block

    * comment like

    * this

    */

@@ -107,39 +36,25 @@

      and not

      like this

     */

  

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

- 

-   Its much easier to spot the block comments if they all start with *,
 

-   and these comments tend to be worth noticing.

- 

- 14) As discussed on irc, the preferred style for expressions is like thi
s:

- 

+   /* if you are doing a single line comment, this method is fine */</cod
e>Its much easier to spot the block comments if they all start with *, and
 these comments tend to be worth noticing.

+   - As discussed on irc, the preferred style for expressions is like thi
s:<code>

  if (expression) {

    statement;

    statement;

  }

- 

- if <space> (expression), the space between the if and expression is requ
ired.

- 

- NOT like this:

- 

+ </code>if <space> (expression), the space between the if and expression 
is required.\\ NOT like this:<code>

  if (expression)

  {

    statement;

    statement;

- }

- 

- 15) The preferred style of formal parameters:

- 

+ }</code>

+   - The preferred style of formal parameters:<code>

  void myFooFunction(param1, param2, param3) {

    statement;

    statement;

- }

- 

- No space after the left paren, no space before the right paren.

- Comma right after the formal param, space right after the comma.  

+ }</code>No space after the left paren, no space before the right paren. 
Comma right after the formal param, space right after the comma.  

  

  

  16) Local variable names. Just a rules of thumb.

  





IP-Address  : 192.139.27.18

Old Revision: http://wiki.metalforge.net/doku.php/coding_style_guide?rev
=1150391190

New Revision: http://wiki.metalforge.net/doku.php/coding_style_guide



-- 

This mail was generated by DokuWiki at

http://wiki.metalforge.net/





More information about the crossfire-wiki mailing list