This file documents the style conventions currently in use in the crawl

This file documents the style conventions currently in use in the Crawl

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.

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 same is true when a function is called:

The same is true when a method is called:

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,

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;
    }

B) Variable naming

C) Variable naming

C) Braces

D) Braces

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.

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.

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.

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.

D) Commenting

E) Commenting

  // note that this function *completely* blocks messaging for monsters

  // Note that this function *completely* blocks messaging for monsters