Coding Standards

From NWN Lexicon
Jump to: navigation, search

Following a set of coding standards benefits a module by making it easy to maintain, troubleshoot, and integrate and helps one organize code for better consistency. The NWN Lexicon project tries to follow all of these coding standards and naming conventions in order to maintain consistency across the reference. It is strongly recommended that, if working in a group project, all members of the group agree to use some kind of coding standard and naming conventions, even if they are not the ones presented here.

Indenting and Overall Structure

Place braces on a new line.

BioWare is not completely consistent in brace placement or indentation; in most places a starting brace appears on a new line (not the same line as the function prototype or "if" statements, for example). This greatly enhances readability and is generally considered the best practice. So an "if" statement would be structured as follows:

if (TRUE)
{
    // ...
}

Use only one statement per line.

An exception would be when readability is greatly enhanced, for example in a "switch" statement:

switch (nCondition)
{
    case 1: sVariable = "one";   break;
    case 2: sVariable = "two";   break;
    case 3: sVariable = "three"; break; 
}

Indent statements according to nested depth.

Statements should be indented an appropriate number of levels according to the nested depth. So, an "if" statement in our void main would appear as follows:

void main()
{
    if (TRUE)
    {
        // ...
    }
}

Use white space to improve readability.

Smart use of white space and carriage returns can help break up a large or nested function call, making it easier to read and to make changes.

action aConvo = ActionStartConversation(
    GetObjectByTag("SOME_TAG"),
    "Hey you!",
    FALSE
);

Identifier and Function Declarations

Declare variable identifiers early.

In general, identifiers should be declared at the top of the function. This makes it easy to find the identifier's type and its initial value. If an identifier is only used once, inside a small block, it can be declared at the point where it is used. For example:

void MyFunction()
{
    // Declare the variables here even if we don't set them until later.
    int nInt;
    object oPC;
 
    // Rest of the script here
}

Use proper capitalization.

The names of functions should be lower case, with the first letter of each word capitalized (i.e., camel case). For example:

int DoSomething(int nKills)
{
    return nKills - 9;
}

Variables should follow the standard naming conventions.

Boolean Conditionals

BioWare is inconsistent in their usage of boolean conditional tests. Sometimes bCondition == 1 is used, sometimes bCondition == TRUE is used, and other times the generally accepted standard of bCondition (or !bCondition) is used. Use the generally accepted standard when dealing with identifiers that begin with the int (boolean) prefix of "b"; use equality tests for numeric data types.

int bTest = TRUE;
int nTries = 3;
 
// boolean test:
if (bTest)
{
    // ...
}
 
// numeric test:
if (nTries > 0)
{
    // ...
}

 author: Charles Feduke, additional contributor(s): Steve Mosely, Michael Nork, pcfung