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

no-reply_wiki at metalforge.org no-reply_wiki at metalforge.org
Sat Jan 19 14:34:16 CST 2008 

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

Date        : 2008/01/19 14:34
User        : kbulgrien
Edit Summary: No indentation of # directives; More doxygen style; Major reformat.

@@ -1,32 +1,32 @@
- The following is a wiki-fied mirror of //crossfire/doc/Developers/programming_guide// from the server source.
+ The following is a wiki-fied reorganization of of //crossfire/doc/Developers/programming_guide// from the server source.
  
- ====== Section 1 - Currently used conventions/hints for new code writers: ======
+ ====== Currently used conventions ======
+ 
+ =====Naming=====
  
    - 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)
-   - Indentation is 4 spaces.  This can be a pain to read, but most functions should be consistent through the function.
+   - Use descriptive variable names.
+     *  ''op'' and ''pl'' should only be used for temporary variables (cycling through the list or the like).
+     *  For variables well defined, use an accurate name (ie, hitter, sack, etc).
+   - Local variable names. Just a rules of thumb. These are ok:<code>
+ int mylongvarname;
+ int my_long_var_name;
+ </code>
+     * Do NOT use caps except for typedefs, enums and defines.
+ 
+ =====Using Objects=====
+ 
    - 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 (eaten by an altar or such).
  
+ =====Code Layout=====
  
+ ====File Header====
  
- ====== Section 2 - Style guide for new additions: ======
- 
-   - Use descriptive variable names.  ''op'' and ''pl'' should only be used for temporary 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 behaviour seriously changes the game.  Adding a new spell does not warrant an //#ifdef//. 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 signed-ness 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 judgment on whether breaking up a long line would make something more or less readable.
-   - Assume all names use one name space.  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, do not use non-standard gcc extensions (%%//%% for comment lines, ability to nest functions, declare arrays with variable bounds, etc.)  Likewise, do not use special system functions, for example, do not assume the target is a BSD or SVR4 system.  If a potentially non-standard function must be used, add checks in the autoconf script and include a version of the function in case it is not on that system.  The keyword here is portability; do not assume everyone else has the same system you have.
-   - Write code that can easily be maintained in the future, not code that is easiest to write quickly.  In other words, do not do the quick and dirty hack, but instead always write code with maintainability and clarity in mind.
-   - Use 4 space indentation.  While a lot of old code may use 2 spaces, a move to 4 spaces makes readability easier.
    - Files are created with standard content blocks.<code>char *rcsid_component_file_ext =
      "$Id: file.ext$";
  /*
   * Project name, brief description
@@ -46,31 +46,32 @@
      * The @file path is important when multiple files in the project may have the same name in different directories.
      * Do not include //trunk// or //branches/1.x// in the @file comment header path. 
      * The @file comment block helps doxygen create meaningful output.
      * The license block requirement is obvious.
-   - Functions are documented like this.<code>/**
-  * A brief descriptive sentence summarizes the function.  An overview ends
-  * at the first period and space, then the detailed information follows.
-  *
-  * @param bla
-  * This is a parameter
-  * @return
-  * returns NULL
-  */</code>
-     * This lets doxygen generate nice documentation.
-   - Use the following block commenting style.<code>/*
-  * Do block comments like this.
-  * Get in the habit of using a
-  * brief and detailed style.
-  */
  
- /*
-   and not
-   like this
-  */
+ ====Directives====
+ 
+   - Only add name options with //#ifdef'//s to the ''config'' file if the behaviour seriously changes the game.  Adding a new spell does not warrant an //#ifdef//. There are already too many options in the ''config.h'' file.
+   - 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.
+ 
+ ====General====
+ 
+   - 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 judgment on whether breaking up a long line would make something more or less readable.
+   - Write code that can easily be maintained in the future, not code that is easiest to write quickly.  In other words, do not do the quick and dirty hack, but instead always write code with maintainability and clarity in mind.
+ 
+ ===Indentation===
+ 
+   - Indentation is 4 spaces.  This can be a pain to read, but most functions should be consistent through the function.
+     * While a lot of old code may use 2 spaces, a move to 4 spaces makes readability easier.
+   - #if directives and friends are not indented.
+ 
+ ===Data Types===
+ 
+   - 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 this are strings.  Continue to use //char//, since the signed-ness of functions that take string options can differ system to system, and generate excessive warnings if the wrong sign is used.
+ 
+ ===Statements===
  
- /* but single line comment using this method is fine */</code>
-     * It is much easier to spot the block comments if they all start with *, and they tend to be worth noticing.
    - As discussed on irc, the preferred style for expressions is like this:<code>
  if (expression) {
    statement;
    statement;
@@ -90,19 +91,74 @@
      * No space after the left parenthesis
      * No space before the right parenthesis
      * Comma right after the formal parameters
      * Space after the commas.  
-   - Local variable names. Just a rules of thumb. These are ok:<code>
- int mylongvarname;
- int my_long_var_name;
- </code>
-     * Do NOT use caps except for typedefs, enums and defines.
-   - To document variables in doxygen, format the comment as shown below:<code>
- int my_var_name; /**< Raison d'etre.. */
- </code>
  
+ ===Comments===
+ 
+   - 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.
+   - Do not use C++ style comments (%%//%%).
+   - Functions are documented like this.<code>/**
+  * A brief descriptive sentence summarizes the function.  An overview ends
+  * at the first period and space, then the detailed information follows.
+  *
+  * @param bla
+  * This is a parameter
+  * @return
+  * returns NULL
+  */</code>
+     * This lets doxygen generate nice documentation.
+   - Use the following block commenting style.<code>/*
+  * Do block comments like this.
+  * Get in the habit of using a
+  * brief and detailed style.
+  */
+ 
+ /*
+   and not
+   like this
+  */
+ 
+ /* but single line comment using this method is fine */</code>
+     * It is much easier to spot the block comments if they all start with *, and they tend to be worth noticing.
+   - To document variables in doxygen, format the comment as shown below:
+     * Simple<code>
+ int a_var_name; /**< Raison d'etre.. */</code>
+     * Multi-line<code>
+ int my_var_name; /**< A very long
+                   *   Raison d'etre.. */</code>
+     * Large group summary, with individuals commented also.<code>
+ /**@{
+  * @name UI Widgets
+  * Widgets for the keybinding dialog
+  */
+ static GtkWidget *fire_label, *run_label, *keybinding_window,
+     *keybinding_button_bind;
+ static GtkListStore *keybinding_store;  /**<Bound key list for bind dialog.*/
+ static GtkTreeSelection *keybinding_selection;
+ /* @} EndOf UI Widgets */</code>
+ 
+ =====Portability=====
+ 
+ This is a cross-platform project.  Do not assume everyone else has the same system you have:
+ 
+   - Do not use non-standard gcc extensions
+     * %%//%% for comment lines
+     * Nested functions
+     * Declaration of arrays with variable bounds
+     * Etc.
+   - Do not use special system functions
+     * Do not assume the target is a BSD, SVR4 system, etc.
+     * If a potentially non-standard function must be used:
+       * Add checks in the autoconf script.
+       * Include a version of the function in case it is not on that system.
+   - Assume all names use one name space.  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)
+ 
+ =====Diagnostics and Error Handling=====
+ 
+   - Log errors/diagnostics with the LOG function.  When doing so, please include the function name - this is especially true for errors.
  
- ====== Section 3 - Sending in patches: ======
+ ====== Sending in Patches: ======
  
    - Send patches on a bug fix or feature enhancement basis individually, and do not make mega-patches.  A diff that changes 10 things is more difficult for developers to review 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, patches are just a bunch of source code, with no indication why it should be incorporated.  Without such commentary, it may be difficult to even determine if the bug it fixes is still there in the source it patches. 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 explicitly state whether or not you want that patch incorporated into the master source.  Many times, a patch may be made available on an expirimental basis which is not ready for widespread distribution.  


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