Style Guide


General	Variables	Structs	Enums	Functions
Macros	Defines	Header Files	C Files

General

Guidelines:

meaningful names shall be used for variables, constants, and functions
variables shall NOT be declared on the same line
opening braces should be on a new line unless the entire scope is on the same line
binary operators shall be surrounded by spaces(e.g., x = 3 + 5)
one space shall be left after commas
global variables should be avoided where they are unnecessary
code shall NOT be split into functions unnecessarily
indentation should use 4 spaces
heap allocation should be minimized
tertiary operators shall NOT be nested
comments shall begin with "//"

Variables

Guidelines:

variables shall use meaningful names
variables shall follow the following naming convention:

// scalar
int           iVariable;
uint32_t      uVariable;
uint64_t      ulVariable;
size_t        szVariable;
bool          bVaribale;

// floating point
float         fVariable;
double        dVariable;

// characters
char          cVariable;
unsigned char ucVariable;

// enums & typedefs
plSomeEnum    tVariable;
plSomeStruct  tVariable;

// pointers
int*          piVariable;
uint64_t*     pulVariable;
plSomeEnum*   ptVariable;
       // ... //
char*         pcVariable;
void*         pvVariable;

// arrays
int           aiVariable[16];
uint64_t      aulVariable[16];
plSomeEnum    atVariable[16];
      // ... //
char          acVariable[16];
void          avVariable[16];

// stretchy buffers
int*          sbiVariable;
uint64_t*     sbulVariable;
plSomeEnum*   sbtVariable;
    // ... //
char*         sbcVariable;
void*         sbvVariable;

// globals
int           giVariable;
char*         gpcVariable;

Structs

Guidelines:

struct names shall use camel case
struct names shall be prefixed with "pl"
structs should always be typedef'd
structs when containing many members, should have members be grouped into sections
struct member names should be aligned with other members in their section
struct private/internal members shall be prefixed with an underscore and placed in the last section labeled "// [INTERNAL]"
public structs should be forward declared
structure tags shall match the structure name with a prefixed underscore
structures should be passed by pointer unless the structure is small

Examples:

// forward declarartion
typedef struct _plPerson plPerson;

// definition
typedef struct _plPerson
{
    int         iAge;
    const char* pcName;

    // favorites & misc
    float fFavoriteFloat;
    int   iAnEvenNumber;

    // [INTERNAL]
    float _fHotness; // 0.0f...10.0f
} plPerson;

Enums

Guidelines:

enum names shall use camel case
enum names shall be prefixed with "pl"
enum names shall be appended with an underscore
enums shall never be used as "types" directly
enums shall be forward declared using "typedef int plSomeEnumName;"

Examples:

// forward declaration
typedef int plChannelType;

// definition
enum plChannelType_
{
    PL_CHANNEL_TYPE_DEFAULT,
    PL_CHANNEL_TYPE_CONSOLE,
    PL_CHANNEL_TYPE_BUFFER
};

// variable
plChannelType tMyChanelType = PL_CHANNEL_TYPE_CONSOLE;

Functions

Guidelines:

function names shall use snake_case
function names shall be prefixed with "pl"
private/internal functions shall have an additional underscore after the "pl" prefix
function declarations should be on a single line
most function definitions should start the function signature on a new line
short and simple functions should be inlined and a single line
function input arguments shall appear before out arguments

Examples:

// public functions (declarations)
int  pl_add_numbers(int iA, int iB);
bool pl_is_button_hovered();

// private/internal functions (declarations)
static float  pl__find_average(float fA, float fB);
static void   pl__fill_buffer (char* pcBuffer, size_t szSize);

// simple functions
static inline pl__add_numbers(int iA, int iB) { return iA > iB ? iA : iB; }

// definitions

int
pl_add_numbers(int iA, int iB)
{
    return iA + iB;
}

static float
pl__find_average(float fA, float fB)
{
    return (fA + fB) / 2.0f; 
}

Macros

Guidelines:

macros should be uppercase with an underscore between words
macros should be prefixed with "PL"
macro arguments shall be surrounded by parenthesis
new macros shall be created sparingly
macros used to "compile out" functions should follow the function naming conventions (e.g., logging, profiling)

Examples:

// Guidelines [1][2][3]
#define PL_GET_MAX(x, y) (x) > (y) ? (x) : (y)

// Guideline [5]
#define pl_initialize_profile_context(tPContext) pl__initialize_profile_context((tPContext))

Preprocessor Defines

Guidelines:

preprocessor defines shall be uppercase with an underscore between words
preprocessor defines shall be prefixed with "PL"

Examples:

#define PL_MAX_GRENADES 1024

Header Files

Guidelines:

header file names shall be camel case
header file names should be short and concise.
header file names shall be prefixed with "pl_"
header file names shall be appended with the following for platform dependent headers:
1. "_win32" for Windows specifics
2. "_linux" for Linux specifics
3. "_macos" for MacOs specifics
4. "_vulkan" for Vulkan specifics
5. "_metal" for Metal specifics
header files should only include standard headers
header files should be split into sections with sections denoted as:

//-----------------------------------------------------------------------------
// [SECTION] my section
//-----------------------------------------------------------------------------

header files should begin with the following:

/*
   <header file name>, v0.1 (WIP)
       * brief description or notes
*/

/*
Index of this file:
// [SECTION] documentation
// [SECTION] includes
// [SECTION] defines
// [SECTION] forward declarations & basic types
// [SECTION] public api
// [SECTION] enums
// [SECTION] structs
*/

C Files

Guidelines:

c file names shall be camel case
c file names should be short and concise.
c file names shall be prefixed with "pl_"
c file names shall be appended with the following for platform dependent c files:
1. "_win32" for Windows specifics
2. "_linux" for Linux specifics
3. "_macos" for MacOs specifics
4. "_vulkan" for Vulkan specifics
5. "_metal" for Metal specifics
c files should be split into sections with sections denoted as:

//-----------------------------------------------------------------------------
// [SECTION] my section
//-----------------------------------------------------------------------------

c files should begin with the following:

/*
   <c file name>, v0.1 (WIP)
       * brief description or notes
*/

/*
Index of this file:
// [SECTION] internal documentation
// [SECTION] includes
// [SECTION] defines
// [SECTION] forward declarations & basic types
// [SECTION] internal api
// [SECTION] internal structs
// [SECTION] public api implementations
// [SECTION] internal api implementation
*/

Table of Contents

General

Variables

Structs

Enums

Functions

Macros

Preprocessor Defines

Header Files

C Files