Well, that's what I get by working on several versions of the code at

the same time... completely confused. Anyway, here's the updated
conventions documentation.


git-svn-id: https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk@5296 c06c8d41-db1a-0410-9941-cceddc491573

1 files changed, 77 insertions, 20 deletions

diff --git a/crawl-ref/docs/coding_conventions.txt b/crawl-ref/docs/coding_conventions.txt
index 2ffc15452d..3fc069cc49 100644
--- a/crawl-ref/docs/coding_conventions.txt
+++ b/crawl-ref/docs/coding_conventions.txt
@@ -4,11 +4,11 @@ Crawl coding conventions
 Introduction
 ============
 
-This file documents the style conventions currently in use in the crawl
+This file documents the style conventions currently in use in the Crawl
 codebase, as well as the conventions that new and/or modified code should
 conform to.  It is explicitly not meant to be a didactic "how to program
-effectively" treatise.  That is something best left to books and websites
-and experience.
+effectively" treatise.  That is something best left to books and websites,
+as well as experience.
 
 Conventions
 ===========
@@ -22,7 +22,7 @@ Empty lines don't need any spacing at all.
 Methods
 -------
 
-If the parameter list of a function runs longer than a line length (80 columns), 
+If the parameter list of a method runs longer than a line length (80 columns), 
 the remaining parameters are usually indented in the lines below.
 
   static void replace_area( int sx, int sy, int ex, int ey,
@@ -32,7 +32,7 @@ the remaining parameters are usually indented in the lines below.
        [...]
   }
 
-The same is true when a function is called:
+The same is true when a method is called:
 
         // place guardian {dlb}:
         mons_place( MONS_GUARDIAN_NAGA, BEH_SLEEP, MHITNOT, true, 
@@ -41,11 +41,67 @@ The same is true when a function is called:
 
 
 There are cases where this is not possible because the parameters themselves
-are too long for that, or because the function is already heavily indented,
+are too long for that, or because the method is already heavily indented,
 but otherwise, this convention should be followed.
 
-Conditionals
-------------
+
+B) Logical operators
+--------------------
+
+Conditionals longer than a line should be indented under the starting bracket.
+This probably seems obvious for simple ifs ...
+
+    if (!player_in_branch(BRANCH_COCYTUS)
+        && !player_in_branch(BRANCH_SWAMP)
+        && !player_in_branch(BRANCH_SHOALS))
+    {
+        _prepare_water( level_number );
+    }
+
+... but it should also be followed for else if conditionals.
+
+        else if (keyin == ESCAPE || keyin == ' '
+                 || keyin == '\r' || keyin == '\n')
+        {
+            canned_msg( MSG_OK );
+            return (false);
+        }
+
+Space allowing, logical connectives of different precedence should use nested 
+indenting.
+
+    case ABIL_MAPPING:          // Gnome + sense surrounds mut
+        if (abil.ability == ABIL_MAPPING
+            && player_mutation_level(MUT_MAPPING) < 3
+            && (you.level_type == LEVEL_PANDEMONIUM
+                || you.level_type == LEVEL_LABYRINTH))
+        {
+            mpr("You feel momentarily disoriented.");
+            return (false);
+        }
+
+If a logical connective needs to be distributed over several lines, 
+the conjunction/disjunction operators (&&, ||) should be placed at the 
+beginning of the new line rather than at the end of the old one.
+
+    else if (you.mutation[mutat] >= 3
+             && mutat != MUT_STRONG && mutat != MUT_CLEVER
+             && mutat != MUT_AGILE && mutat != MUT_WEAK
+             && mutat != MUT_DOPEY && mutat != MUT_CLUMSY)
+    {
+        return false;
+    }
+
+Since conjunctions (&&) take precedence over disjunctions (||), pure 
+conjunctive logical connectives don't need to be bracketed, unless this is 
+absolutely vital for understanding. (Nested indenting helps here.)
+
+    if (you.skills[SK_ICE_MAGIC] > you.skills[SK_FIRE_MAGIC]
+        || you.skills[SK_FIRE_MAGIC] == you.skills[SK_ICE_MAGIC]
+           && you.skills[SK_AIR_MAGIC] > you.skills[SK_EARTH_MAGIC])
+    {
+        book = BOOK_CONJURATIONS_II;
+    }
 
 In a switch conditional, the case listings don't have to be indented, though
 the conditional statements should be.
@@ -77,7 +133,7 @@ Comparisons using the ? shortcut may be indented ...
             beam.thrower = (cause) ? KILL_MISC : KILL_YOU;
 
 
-B) Variable naming
+C) Variable naming
 ------------------
 
 When naming variables, use underscores_as_spaces instead of mixedCase.  Other 
@@ -134,7 +190,7 @@ But structures tend to use underscores
   };
 
 
-C) Braces
+D) Braces
 ---------
 
 Braces are always put on their own lines.
@@ -177,7 +233,8 @@ Otherwise, place braces.
                        you.x_pos, you.y_pos, MHITYOU, MONS_PROGRAM_BUG);
     }
 
-Also place braces if this is only the case because of one or more comment lines.
+Also place braces if this is only the case because of one or more comment 
+lines.
 
         for (j = 0; j < num_to_make; j++)
         {
@@ -203,13 +260,13 @@ use
 Place braces as per the conventions above.
 
 Else, whenever if-conditional nesting can't be avoided, always use braces. I 
-can't find an example where that isn't already necessary for logical reasons, so 
-these should be really rare.
+could't find an example where that isn't already necessary for logical reasons,
+so these should be really rare.
 
 In a row of if-else if-statements or in a switch-case loop, the optional braces 
-should be used if the bigger part of statements needs braces for logical reasons 
-or because of one of the conventions above. Otherwise, they
-may be omitted.
+should be used if the bigger part of statements needs braces for logical 
+reasons or because of one of the conventions above. Otherwise, they may be 
+omitted.
 
     if (mons_neutral(monster))
     {
@@ -235,8 +292,8 @@ braces may be omitted.
               water_spaces++;
       }
 
-The same is true for combined for- and if-conditionals as long as all statements 
-fill less than four lines.
+The same is true for combined for- and if-conditionals as long as all 
+statements fill less than four lines.
 
     for (i = 0; i < MAX_SHOPS; i++)
         if (env.shop[i].type == SHOP_UNASSIGNED)
@@ -268,14 +325,14 @@ leave a free line between them.
     return coord_def(0, 0);
 
 
-D) Commenting
+E) Commenting
 -------------
 
 If you feel that a method is complicated enough to be difficult to understand, 
 or has restrictions or effects that might not be obvious, add explanatory 
 comments before it. You may sign your comments if you wish to.
 
-  // note that this function *completely* blocks messaging for monsters
+  // Note that this function *completely* blocks messaging for monsters
   // distant or invisible to the player ... look elsewhere for a function
   // permitting output of "It" messages for the invisible {dlb}
   // Intentionally avoids info and str_pass now. -- bwr