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

no-reply_wiki at metalforge.org no-reply_wiki at metalforge.org
Thu Mar 22 07:02:17 CDT 2007 

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

Date        : 2007/03/22 07:02
User        : ryo
Edit Summary: update

@@ -1,15 +1,15 @@
  The following is a wikified mirror of //crossfire/doc/Developers/programming_guide// from the server source.
  
  ====== Section 1 - currently used conventions/hints for new code writers: ======
  
-   - variable abbreviations - op is short for object pointer, ob is for object, and pl is for player.
-   - Some functions are named using the conventions above - the naming effects 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 read, but most functions should be consistent through the function.
+   - variable abbreviations - ''op'' is short for object pointer, ''ob'' is for object, and ''pl'' is for player.
+   - Some functions are named using the conventions above - the naming effects what options they take (''insert_ob_in_ob'' takes 2 object structures)
+   - Identation is 4 spaces.  This can be a pain to read, 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 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.
-   - 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.
+     * ''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.
+   - 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 (eaten by an altar or such).
  
  
  
  ====== Section 2 - Style guide for new additions: ======
@@ -21,9 +21,9 @@
    - 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. This makes debugging of such functions easier, and also makes it better known to other developers if that function might be useful to them.
    - 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 the line would otherwise be 83 characters long.  Xterms can be resized to most any width.  However, use your judgement on whether breaking up a long line would make something more or less readable.
-   - 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)
+   - 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)
    - 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 - 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.  They key word here is portability - don't assume everyone else has the same system as you do.
    - 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.
    - 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>/*
@@ -69,17 +69,17 @@
  
  
  ====== Section 3 - sending in patches: ======
  
-   - 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 me to look over and understand as unrelated changes might be going on.  It is also harder for me to reject part of a patch (feature X is nice, but Y doesn't work).
-   - Please state in the message included with the patch what it fixes/changes. Too often, I get patches which is just a bunch of source code, and I have no idea if I want to incorporate it, or even if the bug is still there. Please also state what version of crossfire the diff is for.
+   - 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 developers to look over and understand as unrelated changes might be going on.  It is also harder to reject part of a patch (feature X is nice, but Y doesn't work).
+   - Please state in the message included with the patch what it fixes/changes. Too often, we get patches which is just a bunch of source code, and we have no idea if I want to incorporate it, or even if the bug is still there. Please also state what version of crossfire the diff is for.
    - I will assume any patches mailed directly to me are to be included. If posting a patch on the mailing list (either source or ftp location), please explicity state whether or not you want that patch incorporated into the master source.  Many times, a patch may be made available on an expiremental basis which is not ready for widespread distribution.  
    - 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:<code>
  diff -c5 (oldfile) (newfile)</code>You can also do diffs of entire directories.  Do do this, type:<code>
  diff -c5 -r (old_directory) (new_directory)</code>An example:<code>
  diff -c5 -r crossfire-0.90.1 crossfire-0.90.2</code>
    - Gnu diff will include files that did not exist before.  Other diff programs may not do this.
    - If your diff looks excessively long and you made a lot of formatting changes, you can add -w to the diff options to have it ignore whitespace. Note that this will then mean that those formatting changes will then be lost.
    - There is no need to make a seperate diff file for each file different (ie, treasure.diff, player.diff, etc).  Assuming you follow steps 1-6, all the diffs can be contained in one file, and patch will deal with it just fine.
-   - If you need to send a map, new archetypes, or other new files where a diff doesn't make since, a uuencoded tar file will work just fine.
+   - If you need to send a map, new archetypes, or other new files where a diff doesn't make sense, a uuencoded tar file will work just fine.
  
  Submit all patches to the Sourceforge patch tracker on http://sourceforge.net/projects/crossfire, and mail an announcement to [[crossfire-devel at lists.real-time.com]].


IP-Address  : 172.186.46.252
Old Revision: http://wiki.metalforge.net/doku.php/coding_style_guide?rev=1167417785
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