+++
title = 'ExectOS Coding Style'
date = 2024-06-18T00:20:07+02:00
+++
This document outlines our coding style guidelines. If you have suggestions for things that should be clarified better,
[contact with us](/contact-us/). With a continuous stream of contributions and patches we would
like the our code base to remain clean and easy to read and maintain.

## General
Each source file should contain a header:
```
/**
 * PROJECT:         ExectOS
 * COPYRIGHT:       See COPYING.md in the top level directory
 * FILE:            path/to/source/file.c
 * DESCRIPTION:     Description of the purpose of the code in this file
 * DEVELOPERS:      Your Name <name@codingworkshop.eu.org>
 */
```
You should only add yourself to the developer list if you are making a significant contribution, which means you
understand the purpose of the code in this file and you can provide support to anyone.

## Indentation and whitespace
 * Set your editor to __4 spaces per tab; never use tabs__.
 * Do not add a space or tab at the end of any line.
 * Indent both a case label and the case statement of the switch statement.
 * When wrapping a too long line, add indentation to match the function call parameter list or expression.
 * Always separate operators with a space on both sides, except after C-style cast operator.
 * Always use a space after comma.
 * A line must not have more than __120 characters__.
```
switch(Condition)
{
    case 1:
        CallFunction();
        break;
    default:
        CallAnotherFunction();
        break;
}

CallOtherFunction(Argument1, Argument2, Argument3,
                  Argument4, Argument5);

Pointer = (PVOID)Address;
```

## Miscellaneous formatting
 * Include exactly one empty line between header and `#include` directives.
 * Put exactly two empty lines after `#include` directives.
 * Include single newline at every file end.

## Identifiers
 * Always use self-describing well chosen identifiers.
 * Use full names such as `Message` over abbreviations such as `Mesg`.
 * Function names and variables start with uppercase letters and use CamelCaseFormatting.
 * Classes, structures, unions and type definitions are UPPERCASE and use underscore.
```
typedef char BOOL;

typedef struct _NEW_STRUCTURE
{
    BOOL Enabled;
    PVOID Pointer;
} NEW_STRUCTURE, *PNEW_STRUCTURE;

XTAPI
VOID
KeStartKernel();
```

## Variable declarations
 * Always declare all variables at the beginning of the function.
 * Use descriptive names, avoid reusing a single variable for different purposes.
 * Always use XT API types over defined in C standard.

## Comments
 * Always comment your code properly.
 * Use only C-style comments.
 * Comment over and under the commented line to avoid producing long lines.
 * Do not annotate your comments with your name or initials.
 * Avoid expressing sentiments, instead explain why you consider the respective code a hack.
```
/* This is a C-style comment */

/* This is a valid
 * multi-line comment */
```

## Documentation
 * We use JavaDoc style comments for API documentation.
 * The comment separators `/**` and `*/` must be present.
 * Every line must be indented.
```
/**
 * Multi-line routine description.
 *
 * @param Parameter1
 *        Description of the first parameter goes here.
 *
 * @param Parameter2
 *        Description of the seconds parameter goes here.
 *
 * @return Short description about return values.
 *
 * @since Information from which version a given function is available.
 *
 * @see Optional link to documentation or reference implementation.
 *
 * @todo Optional description, telling what is missing in the function implementation.
 */
```

## Miscellaneous
 * Use NULLPTR instead of 0 for pointers.
 * Avoid using assignments in while loops.
 * Never use goto statements.
 * Never use spaces around unary operators.
 * Always put braces (`{` and `}`) on their own lines.
 * One-line control clauses should use braces as well.
 * Do not use reverse logic in control clauses.
 * Do not use spaces around unary operators, before comma and semicolon, or between control statements and their
   parentheses.