QNet/CONVENTION.md

QNET code convention

This document contains the code convention for the QNet library. These conventions help with the readability and maintainability of the code. When changing or writting new code make sure that the code complies with these convention. Failure to do so will invalidate the pull request until the code complies.

File layout

When writting code in a file the following layout is expected:

• QNet file includes
• Standard c library includes
• Other library includes
• Macro's
• Types
• Enums
• Structures
• Functions

Using a consistent layout between files will make it easier for other people to find what they need when reading the code. You may deviate from this convention ONLY when ABSOLUTLY necessary for the code to function.

Code layout

When writting code there is also a certain layout that will need to be followed.

brackets

When implementing functions, structs, enums, loop or if-statements the first curly bracket should always be on the same line. The last bracket should get it's only line, unless you are defining an inline function. An example of well formated brackets is:

if (condition) {
    // Do something
}

Naming convention

The naming convention makes sure the names in the code are consistent making it easier to read and understand. When naming anything it is important that the name clearly describes the purpose. Doing this will avoid confusion and make it easier for others to start working on the project.

Types

When creating a new type the snake_case naming convention is used togethor with the prefix qnet and the postfix type. An example of a well named type is:

typedef unsigned int qnet_age_type;

Structs

For structures the snake_case naming convention is used togethor with the qnet prefix. An example of a well named struct is:

struct qnet_server {
    char *ip;
    unsigned short port;

    int socket;
}

Enums

To easily differentiate enums from structs and types UpperCamelCase is used togethor with the prefix QNet. The values of an enum will however use SCREAMING_SNAKE_CASE with the name of the enum as it's prefix. When creating the values the value should be set directly in the code. An example of a well named enum is:

typedef enum {
    QNET_SERVER_ERROR_OK = 0,
    QNET_SERVER_ERROR_FAILED_TO_CREATE_SOCKET = -1,
    QNET_SERVER_ERROR_COULD_NOT_BIND_ADDRESS = -2
} QNetServerError;

Macro's

When defining macro's SCREAMING_SNAKE_CASE will also be used togethor with the prefix qnet. An example of a well named macro is:

#define QNET_SERVER_INVALID_SOCKET -1

Functions

snake_case is used when naming fuction with the prefix qnet. An example of a well named function is:

int qnet_server_create(char *ip, unsigned short port);

Variables

Variables will also use snake_case without any prefixes. An example of a well named variable is:

const char *server_ip_address = "127.0.0.1";

Comments

When writting code you should comment to make clear how the code works. However to many or bad comments can have a reverse effect. Thats why the following convention has been setup.

Files

For every code file you create (headers, source, etc) the following header should be added:

/*
 * Copyright (C) Tristan Franssen, <tristanfranssen@strawhats.nl>.
 *
 * This software is licensed under the Apache License, Version 2.0 (the "License");
 * You may not use this file except in compliance with the License.
 * You may obtain a copy of the License in the file LICENSE or at
 * http://www.apache.org/licenses/LICENSE-2.0
 */

Functions

When creating a function you should ALWAYS comment it. How you comment it however depents on where the function is defined and implemented. If the function is defined in a header the comment for the function in the header should look something like this:

/**
 * @brief description of the function.
 *
 * @param paramName description of parameter.
 * @return what is returned on success and on error. Do i need to free the returned value?
 */

This style of comment is also used when the function is defined and implemented in a source file. For functions that are only implemented in the source file the header should only have the @brief added.

Code

When writting code some parts of the code may be complex or unclear. Here you could use a comment to help other developers understand the code without needing to spend hours reading every line. When commenting a single line you should place the comment at the end of that line of code. However when commenting about multiple line you should place it on it's own line at the start of the code you want to comment. An example of well commented code is:

// Calculates the avarage age of the users
unsigned int user_age_length = 4;
int users_age = [ 28, 59, 23, 45 ];
int avarage = 0;

for (unsigned int index = 0; index < user_age_length; index += 1) {
    avarage += user_age[index]; // Adds all ages togethor to get the total
}

avarage /= user_age_length;