Conventions

Naming

File naming

File names should be in camelCase and should be descriptive of the file's contents. It should explain what the file does.

Examples: - getUsers.js, makes a get request to the /users endpoint - createUser.js, makes a post request to the /users endpoint - deleteUser.js, makes a delete request to the /users endpoint - updateUser.js, makes a put request to the /users endpoint - device-management.js, adds device management functionality to device management page - device-management.html, the device management page

Variable naming

All variable names should be in camelCase and should be descriptive of the variable's contents. It should explain what the variable is. The variable name should start with a noun (car, name, event, etc.). Following the noun, it should be completed with an adjective (carSize, nameCount, eventId, etc.).

Examples: - users, an array of users - user, a single user - userCount, the number of users - uidLength, the length of a user's uid - packetId, the id of a packet

there are exceptions to this rule for the following variables:

macros in C/C++, these should be in SCREAMING_SNAKE_CASE

#define SCREAMING_SNAKE_CASE 1

classes in css, these should be in kebab-case

.kebab-case {
    color: brown;
}

Function naming

All function names should be in camelCase and should be descriptive of the function's contents. It should explain what the function does.

Examples: - getUsers(), gets all users from the database - createUser(), creates a new user in the database - deleteUser(), deletes a user from the database - updateUser(), updates a user in the database - showTodaysEvents(), shows all events that are happening today

Class naming

All class names should be in PascalCase and should be descriptive of the class's contents. It should explain what the class does.

Examples: - RfidManager, manages all rfid related functionality - HttpsManager, manages all https related functionality

Key naming

All key names should be in camelCase and should be descriptive of the key's contents. It should explain what the key is.

Examples: - user, a single user - userId, the id of a user - userArray, an array of users

File headers

Source files should always contain a header mentioning the author, dates, and a description. Below is an example about the format that should be used.

This format should be used for all source files.

/**
 * @Authors         {Name of Author}
 * @Date created    {Date of creation (e.g. 16-09-2024)}
 * @Date updated    {Date of edit + name (e.g. 16-09-2024 (By: Laurens Leusink))}
 * @Description     {A short description mentioning the contents and objectives of the source code}
 */

Code comments

For code comments it's important to differentiate between descriptive comments and notes. Function definitions should always use the descriptive comment format as they will be highlighted and provide a better picture when scanning through a document.

When aligning comments, make sure to use only spaces and not tabs. This will make sure the comments are aligned correctly in the IDE. You can change the behavior of the tab key in the settings of your IDE.

Descriptive comments

For source files like PHP and C++ code the format below can be used. It is important to add the double * on the first line to make sure the IDE sees this as a description.

When listing parameters the @param key should be used. When a function returns something, the @return key should be used. After this mention the object type (e.g. Date, String, Object etc.). With those 2 present you can name the input variable name and a short description of the file. Make sure to not use : after the variable name.

/**
 * Update the event details element with the event data
 * @param {object} eventData        - The event data object containing the event details
 * @param {number} participantCount - The number of participants for the event
 * @return {bool} success           - Returns true if the event details were updated successfully and false if not
 */

Note comments

In-line code comments can be used to explain a specific line of code. This is useful when the code is not self-explanatory or when you want to explain a specific part of the code.

There are 2 ways to add in-line comments. The first is to add a comment on the same line as the code. This is useful when you want to explain a specific part of the code. The second is to add a comment on the line above the code. This is useful when you want to explain a block of code.

Multi line comments

If a piece of code requires a lof of explanation, or you need to get attention of the reader, you can choose to use multi line comments. This is useful when you want to explain a block of code.

/*
 * This is a multi line comment
 */

Make sure to not use the double * as this is only used for descriptive comments!

Single line comments

For normal comments you can put the comment right above or right next to the code. This is useful when you want to explain a specific part of the code.

// A single line comment

Marking TODO's

When you want to mark a piece of code as a TODO, you can use the following format. This will make it easier to find the TODO's in the code and will make it easier to find them in the IDE.

// TODO {Description of the TODO}

Responses

JSON

Use JSON as the response format for all API endpoints. The response should always contain a success and message key. The success key should be a boolean and the message key should be a string. The message key should contain a short description of the response. The data should be after the message key.

Success

{
    "success": true,
    "message": "User list fetched successfully.",
    "foo": "bar",
    "fooArray": [
        {
            "foo": "bar",
            "foo1": "bar1"
        },
        {
            "foo": "bar",
            "foo1": "bar1"
        }
    ],
    "foo1": "bar1"
}

Fail

{
    "success": false,
    "message": "Error: {error message}",
    "foo": null,
    "fooArray": null,
    "foo1": null
}

HTTP

Use the correct HTTP status codes for the response. Use the Mozilla HTTP status code documentation for reference.

SQL query

When making a SQL query, make use of prepared statements. This will prevent SQL injection. Use the W3Schools PHP prepared statements documentation for reference.
Example:

$uid = 21;

$stmt = $conn->prepare("SELECT * FROM users WHERE uid = ?");
$stmt->bind_param("i", $uid);

$stmt->execute();
$result = $stmt->get_result();

$stmt->close();