Guidelines

Note: This file may be subject to change once setup of the DevOps environment is has been completed.

Coding Guidelines

PHP

• There should be 1 empty line between functions.
• Functions may only do 1 action and the name should represent the action accurately.
• Functions which could be hard to understand at a first glance should include PHPDocs (/* ... */) above them describing their action.
• If necessary .blade.php files may contain comments ({{-- ... --}}) as well.
• Do not use html commenting (<-- ... -->).
• If possible use Artisan to generate files, instead of making them manually.
• Avoid data manipulation inside .blade.php files.
• For recurring bits of front-end code use Blade's subviews.
• Front-end layout should be defined in Blade's components.
• Use Blade's CSRF protection.
• Avoid raw php inside .blade.php files.
• Variables containing user input should always be sanitized as soon as possible.
• If a variable does not change during execution it should be marked as const.
• A variable name should always describe it's value. No ambiguous names such as $a or $b. Simple variable names are only allowed when used as a counter inside of a loop.
• Avoid global and static variables.
• Bool variable names should always be confirming. Correct example: $is_avaiable, incorrect: $is_not_available.
• const variables have to be declared as you would any other variable, do not use define().
• Avoid return statements not returning any value.
• Do not use continue.
• A comma is always followed by a space.
• Operators are always surrounded by spaces.
• A code block is opened on a different line from its definition.
• A code block is ended on a separate line.
• Lengthy conditions should jump to the next line.
• Prefer php native functions over externally added functions. For instance prefer rand() over Faker's randomNumberBetween().
• If something you have started working on is incomplete. Mark it with //TODO: <short description of what needs doing>.
• There should never be any TODOs on dev or main.
• Code should never contain things such as connection strings, passwords or secrets. Use the .env file.

Javascript

• There should be 1 empty line between functions.
• Functions may only do 1 action and the name should represent the action accurately.
• Always use let instead of var.
• Elements within a forEach should be named accurately to represent the parent object.
• Use querySelector instead of getElementById or jQuery selector.
• Do not use functions that interrupt the flow of the webpage such as alert.
• Define all DOM elements you need to use at the top of the script as const.
• Even if not necessary, use ; to end lines.
• A code block is opened on the same line as its definition.
• Use async for AJAX.
• Only use AJAX when you need to POST a form without reloading the page.
• There should never be any TODOs on dev or main.
• A variable name should always describe it's value. No ambiguous names such as let a or let b. Simple variable names are only allowed when used as a counter inside of a loop.
• Set onClick on buttons within the HTML instead of in your script (see mapScript.js if you need an example).

Naming Conventions

• Script files should be camelCase.
• Class names use PascalCase.
• Function names use camelCase.
• Variable names use snake_case.
• Model properties and relationships should use snake_case.
• const Variable names use SCREAMING_SNAKE_CASE.
• Files generated with Artisan get named automatically. Do not change these names after generation.
• Files have different case types depending on their purpose, be consistent inside folders.
• A comma is always followed by a space.
• Operators are always surrounded by spaces.

GitHub Guidelines

Branching Rules

• For each userstory each user is allowed to make their own branch. The user branch should be directly based on dev and has the following format: <UserstoryNr>_<User>.
• Aside from user branches. Hotfix branches based on dev are also allowed.
• Main is updated once per sprint. (approximately Every 2 weeks)

Review Rules

• 4 reviews are required to merge from dev into main.
• 2 reviews are required from any branch into dev. (Excluding the code owner's review)
• Coding guideline violations is a valid reason for rejection.
• Reviews should come with useful feedback. Not just criticism.
• Use the Code Highlight tool.
• Merge conflicts should be solved by the merge request's owner.
• Draft merge requests don't have to be reviewed. If it is a draft be sure to mark it with the WIP label.
• The merge request owner is responsible for the assigning reviewers.
• After a merge request has passed reviews, the bound userstory will be checked for completion using the DoD.

Merge requests rules

• Merge requests should describe the changes it will make to the branch it is pushing to.
• Merge requests may not be passed if they are connected to an open issue.
• Code within a merge request should be successfully tested with unit tests.
• Merge requests to master should never contain debug code.
• Never include output files, for instance .log.

Issue Rules

• Use the issues for bugs, glitches and thrown errors.
• An issue should include how to reproduce the issue.
• An issue should include the expected result and current result.
• If a pull request solves an issue, connect it to the issue.

SCRUM Guidelines

• Userstories should be split up into tasks which could realistically be completed by one person.
• If you don't have a task assigned to you currently or just finished your last task ask for a new one.