README.md

PC Futures Coding Standards

Examples are written in PHP, but should be followed for all relevant languages.

---

Import statements should be grouped by location & type

Groups include and should be in the following order:

1. Third party modules (vendor/node_modules)
2. Absolute imports
3. Relative imports
4. Aliased imports

❌ Incorrect:

use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Collection;
use App\Models\Traits\SoftDeletes\SoftDeletes;
use ReflectionMethod;
use Illuminate\Database\Eloquent\Relations\MorphToMany;
use ReflectionClass;
use Carbon\Carbon;
use App\Models\HistoryPivotChangeAttribute;
use App\Models\History;
use Auth;

✔️ Correct:

use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\MorphToMany;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Collection;
use Carbon\Carbon;

use App\Models\Traits\SoftDeletes\SoftDeletes;
use App\Models\HistoryPivotChangeAttribute;
use App\Models\History;

use ReflectionMethod;
use ReflectionClass;
use Auth;

---

Import statements should be ordered by length in descending order:

❌ Incorrect:

use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\MorphMany;
use Illuminate\Database\Eloquent\Relations\MorphToMany;

✔️ Correct:

use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\MorphToMany;
use Illuminate\Database\Eloquent\Relations\MorphMany;

---

Code should be indented by 4 spaces

❌ Incorrect:

function add(int $x, int $y): int {
  return $x + $y;
}

✔️ Correct:

function add(int $x, int $y): int {
    return $x + $y;
}

---

Curly brackets should appear on the same line as statements

❌ Incorrect:

function add(int $x, int $y): int
{
    return $x + $y;
}

✔️ Correct:

function add(int $x, int $y): int {
    return $x + $y;
}

---

Line breaks should be used to separate functionality differences

❌ Incorrect:

function add(int $x, int $y): int {
    $result = $x + $y;
    return $result;
}
function subtract(int $x, int $y): int {
    $result = $x - $y;
    return $result;
}

✔️ Correct:

function add(int $x, int $y): int {
    $result = $x + $y;

    return $result;
}

function subtract(int $x, int $y): int {
    $result = $x - $y;

    return $result;
}

---

Variables and functions should be typed

❌ Incorrect:

function add($x, $y) {
    return $x + $y;
}

✔️ Correct:

function add(int $x, int $y): int {
    return $x + $y;
}

---

Single quotes should be preferred over double quotes

❌ Incorrect:

function appendGreeting(string $name): string {
    return "Hey there, " . $name;
}

✔️ Correct:

function appendGreeting(string $name): string {
    return 'Hey there, ' . $name;
}

---

Spaces should be used to separate words and symbols

❌ Incorrect:

$str='hello'+'world';

✔️ Correct:

$str = 'hello' + 'world';

---

Math operators should ONLY be used for mathematical operations

❌ Incorrect:

$arr = ['hello'] + ['world'];

$str = 'hello' + 'world';

✔️ Correct:

$arr = array_merge(['hello'], ['world']);

$str = 'hello' . 'world';

---

Inline if statements are ONLY allowed if they're used as Guard Clauses

❌ Incorrect:

function validate(mixed $x): bool {
    if (is_null($x)) return false;
    elseif (is_string($x) return false;
    else return true;
}

✔️ Correct:

function validate(mixed $x): bool {
    if (is_null($x)) return false;
    if (is_string($x)) return false;

    return true;
}

---

Variables, keys and functions should be camelCased

❌ Incorrect:

function validate_a_variable(mixed $the_value): bool {
    $is_valid = true;

    if (is_string($the_value)) {
        $is_valid = false;
    };

    return $is_valid;
}

✔️ Correct:

function validateAVariable(mixed $theValue): bool {
    $isValid = false;

    if (is_string($theValue)) {
        $isValid = true;
    };

    return $isValid;
}

---

Global constants should be used instead of magic numbers

❌ Incorrect:

function calculateCircumference(float $radius): float {
    return 2 * 3.141592654 * $radius;
}

✔️ Correct:

const PI = 3.141592654;

function calculateCircumference(float $radius): float {
    return 2 * PI * $radius;
}

---

Global constants should be CAPS_CASE

❌ Incorrect:

const pi = 3.141592654;

function calculateCircumference(float $radius): float {
    return 2 * pi * $radius;
}

✔️ Correct:

const PI = 3.141592654;

function calculateCircumference(float $radius): float {
    return 2 * PI * $radius;
}

---

SQL column names should be snake_cased

❌ Incorrect:

$table->string('firstName');

✔️ Correct:

$table->string('first_name');

---

Secret values (passwords, salts, encryption keys) should NEVER be committed to GitHub and should be stored in an environment (.env) file

❌ Incorrect:

$secret = 'secret_value';

✔️ Correct:

$secret = config('app.secret_value');