website/content/contributing/coding-style.md

+++ 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. 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.