SingOS/SingOS_Coding_Practice.md

SingOs Coding Practice

Version 1 -- A first draft at formalizing a common coding practice for SingOS Development

On naming

We encourage long but descriptive identifier names like,

token_string_to_id_map

as opposed to,

tok_map (BAD)

(Yes, it's a made up example).

Short names like 'i' and 'j' may be used for super obvious iteration indexes only, otherwise, if the body of the loop is big, we still prefer something more explicit like:

token_index

On casing

We use snake-case for all identifiers consisting of multiple words; this means that words are underscore seperated.

For variable and procedure names, every letter is lowercase:

our_very_important_variable
our_very_important_procedure

For all typenames (structs, enums, unions, etc.), every word begins with a capitalized letter:

Our_Very_Important_Type

(An exception is made for primitive types like int, float, double, etc).

For value constants (#defines), every letter is uppercase (all-caps):

OUR_VERY_IMPORTANT_CONSTANT

Macros acting like procedures should be capitalized like procedures, but with parameter names in all-caps:

our_very_important_macro(PARAMETER, OTHER_PARAMETER)

On indentation

We use 4 spaces per indent, at least in C-style languages. (^:

On brace-placement

What do we prefer? This:

if (something)
{
    do_stuff();
}
else
{
    this_other_thing();
}

Or this:

if (something) {
    do_stuff();
}
else {
    this_other_thing();
}

On return statements

We prefer an explicit else case even though a return was found in an above branch:

if (some_condition)
{
    return "Olga";
}
else
{
    return "Finn";
}

As opposed to:

(BAD)

if (some_condition)
{
    return "Olga";
}

return "Finn";

(BAD)