pokeruby/pokeemerald style guide

style-guide.md

Style Guide - pokeruby/pokeemerald

Version 0.1

Comments

When describing a system/component in-depth, use block comment syntax.

/*
 * This is an in-depth description of the save block format. Its format is as follows:
 *
 * Sectors  0 - 13: Save Slot 1
 * Sectors 14 - 27: Save Slot 2
 * ...
 */

When briefly describing a function or block of code, use a single-line comments placed on its own line. There should be a single space directly to the right of //.

// This is supplemental information for the function. If there is a bunch of info, it should
// carry on to the next line.
void ProcessSingleTask(void)
{
   // Short comment describing some noteworthy aspect of the code immediately following.
   ...
   // Comments should be capitalized and end in a period.
}

When tagging a data structure that corresponds to an enum or some noteworthy value, place the comment on the same line as the code.

const u8 gPlantlikeMons[] =
{
    FALSE, // SPECIES_BULBASAUR
    FALSE, // SPECIES_IVYSAUR
    TRUE,  // SPECIES_VENUSAUR
    FALSE, // SPECIES_CHARMANDER
    ...
};

Naming

Functions should be formatted in PascalCase.

void ThisIsCorrect(void);

Local variables should be formatted in camelCase.

int thisIsCorrect = 0;

Global variables should be prefixed with g and use camelCase.

extern int gMyGlobalVariable;

Static variables should be prefixed with s and use camelCase.

static u8 sMyStaticVariable = 0;

Struct names should be formatted in PascalCase. Struct fields should be camelCase.

struct MyStruct
{
    u8 firstField;
    u16 secondField;
    ...
};

Enums and #define constants should be formatted in upper case and separated by underscores.

#define MAX_LEVEL 100

enum
{
    COLOR_RED,
    COLOR_BLUE,
    COLOR_GREEN,
};

Macro names should be upper case and separated by underscores.

#define ADD_FIVE(x) ((x) + 5)

Whitespace

All .c and .h files should use 4 spaces--not tabs. Assembler files (.s) use tabs.

Assignments and comparison operators should have one space on both sides of =.

int i = 0; // correct
int i=0;   // incorrect

a > b // correct
a>b   // incorrect

The incrementor and decrementor operators should NOT have a space.

i++;  // correct
i ++; // incorrect

A control statement should have a space between them and their expressions, and the opening bracket should be on the next line.

for (...)
{
    // correct
}

for(...) {
    // incorrect
}

A switch statement's cases should left-align with the switch's block.

switch (foo)
{
case 0: // correct
	...
    break;
}

switch (foo)
{
    case 0: // incorrect
    	...
        break;
}

A single empty line should follow a block.

int MyFunction(int bar)
{
    int foo = 0;
    if (bar)
        foo++;

    return foo; // incorrect
}

int MyFunction(int bar)
{
    int foo = 0;
    if (bar)
        foo++;
    return foo; // incorrect
}

A chain of if-else statements in which any block is more than one line of code should use braces. If all blocks are single-line, then no braces are necessary.

if (foo) // correct
{
    return 1;
}
else
{
    MyFunction();
    return 0;
}

if (foo) // incorrect
    return 1;
else
{
    MyFunction();
    return 0;
}

Control Structures

When comparing whether or not a value equals 0, don't be explicit unless the situation calls for it.

if (runTasks) // correct
    RunTasks();

if (runTasks != 0) // incorrect
    RunTasks();
    
if (!PlayerIsOutside()) // correct
    RemoveSunglasses();

if (PlayerIsOutside() == 0) // incorrect
    RemoveSunglasses();

End all switch cases with break, unless omitting break is necessary for matching the original program flow.

void MyFunction(void)
{
    switch (color)
    {
    ...
    case RED:
        ...
        break; // correct
    }

    return;
}

void MyFunction(void)
{
    switch (color)
    {
    ...
    case RED:
        ... // incorrect
    }

    return;
}

When writing a for or while loop with no body, use a semicolon ; on the same line, rather than empty braces.

for (i = 0; gParty[i].species != SPECIES_NONE; i++); // correct

for (i = 0; gParty[i].species != SPECIES_NONE; i++) // incorrect
{ }

Disagree with the last statement: preference is to have either empty braces on the next line (which you flag as incorrect) or a lone semicolon on the next line with +1 indent level:

for (i = 0; gParty[i].species != SPECIES_NONE; i++)
    ;

This way, it's more obvious to the reader that the loop body is intentionally empty.