openvk/CODE-STYLE.md

Names

Namespace Names

Namespaces should be written in PascalCase.

File Names

Code directories should have their name written in PascalCase. Code files should contain only one class and have the name of that class. In case of multiple class definitions in one file, it's name should be the same as the "primary" class name. Non-code directories, non-class and non-code files should be named in lisp-case.

Variable Names

Variable names should be written in camelCase. This also applies to function arguments, class instance names and methods.

Constant Names

Constants are written in SCREAMING_SNAKE_CASE, but should be declared case-insensetive.

Class Names

Classes in OpenVK should belong to openvk\ namespace and be in the corresponding directory (according to PSR-4). Names of classes should be written in PascalCase.

Function Names

camelCase and snake_case are allowed, but first one is the recommended way. This rule does not apply to class methods, which are written in camelCase only.

---

Coding Rules

File header

All OpenVK files must start with <?php open-tag followed by declare(strict_types=1); on the same line. The next line must contain namespace. The lines after must contain use-declarations, each on it's own line (usage of {} operator is OK), if there is any. Then there must be an empty line. Example:

<?php declare(strict_types=1);
namespace openvk;
use Chandler\Database\DatabaseConnection;
use Nette\Utils\{Image, FileSystem};

class ...

NULL

Null should be written as constant, all-uppercase: NULL.

Nullable (optional) pointer arguments

Optional pointer arguments should default to nullptr: function something(&int? $myPointer = nullptr). nullptr must be written in lisp-case (lowercase).

Comparing to NULL

In OpenVK is_null is the preferred way to check for equality to NULL. ?? must be used in assignments and where else possible. In case if value can either be NULL or truthy, "boolean not" should be used to check if value is not null: if(!$var).

Arrays

Arrays must be defined with modern syntax: [1, 2, 3] (NOT array(1, 2, 3)). Same applies to list construction: use [$a, , $b] = $arr; instead of list($a, , $b) = $arr;

Casts

Typecasts must be done with modern syntax where possible: (type) $var. Int-to-string, string-to-int, etc conversions should also be dont with modern casting syntax where possible, but should use ctype_ functions where needed. gettype, settype should be used in dynamic programming only.

Goto

goto should be avoided.

continue n;

It is preferable to use continue n, break n instead of guarding flags:

# COOL AND GOOD
foreach($a as $b)
    foreach($b as $c)
        if($b == $c)
            break 2;

# BRUH
foreach($a as $b) {
    $shouldBreak = false;
    foreach($b as $c)
        if($b == $c)
            $shouldBreak = true;
    
    if($shouldBreak)
        break;
}

Comments

In OpenVK we use Perl-style # for single-line comments.

---

Formatting

Variables

It is preferable to declare only one variable per line in the code.

Indentation

All things in OpenVK must be properly indented by a sequence of 4 spaces. Not tabs.
When there are several variable declarations listed together, line up the variables:

# OK
$photos = (new Photos)->where("meow", true);
$photo  = $photos->fetch();
$arr    = [
    "a"  => 10,
    "bb" => true,
];

# NOT OK
$photos = (new Photos)->where("meow", true);
$photo = $photos->fetch();
$arr    = [
    "a" => 10,
    "bb" => true,
];

Tab/Space

• Do not use tabs. Use spaces, as tabs are defined differently for different editors and printers.
• Put one space after a comma and semicolons: exp(1, 2) for($i = 1; $i < 100; $i++)
• Put one space around assignment operators: $a = 1
• Always put a space around conditional operators: $a = ($a > $b) ? $a : $b
• Do not put spaces between unary operators and their operands, primary operators and keywords:

# OK
-$a;
$a++;
$b[1] = $a;
fun($b);
if($a) { ... }

# NOT OK
- $a;
$a ++;
$b [1] = $a;
fun ($b);
if ($a) { ... }

Blank Lines

• Use blank lines to create paragraphs in the code or comments to make the code more understandable
• Use blank lines before return statement if it isn't the only statement in the block
• Use blank lines after shorthand if/else/etc

# OK
if($a)
    return $x;
    
doSomething();

return "yay";

# NOT OK
if($a) return $x; # return must be on separate line
doSomething(); # doSomething must be separated by an extra blank line after short if/else
return "yay"; # do use blank lines before return statement

Method/Function Arguments

• When all arguments for a function do not fit on one line, try to line up the first argument in each line:

• If the argument lists are still too long to fit on the line, you may line up the arguments with the method name instead.

Maximum characters per line

Lines should be no more than 80 characters long.

Usage of curly braces

• Curly braces should be on separate line for class, method, and function definitions.
• In loops, if/else, try/catch, switch constructions the opening brace should be on the same line as the operator.
• Braces must be ommited if the block contains only one statement AND the related blocks are also single statemented.
• Nested single-statement+operator blocks must not be surrounded by braces.

# OK
class A
{
    function doSomethingFunny(): int
    {
        return 2;
    }
}

if(true) {
    doSomething();
    doSomethingElse();
} else {
    doSomethingFunny();
}

if($a)
    return false;
else
    doSomething();
    
foreach($b as $c => $d)
    if($c == $d)
        unset($b[$c]);

# NOT OK
class A {
    function doSomethingFunny(): int {
        return 2;
    }
}

if(true) {
    doSomething();
    doSomethingElse();
} else
    doSomethingFunny(); # why?

if($a) {
    return false;
} else {
    doSomething();
}
    
foreach($b as $c => $d) {
    if($c == $d)
        unset($b[$c]);
}

# lmao
if($a) { doSomething(); } else doSomethingElse();

if/else, try/catch

• Operators must not be indented with space from their operands but must have 1-space margin from braces:

# OK
if($a) {
    doSomething();
    doSomethingElse();
} else if($b) {
    try {
        nukeSaintPetersburg('😈');
    } finally {
        return PEACE;
    }
}

# NOT OK
if ($a) { # do not add space between control flow operator IF and it's operand
    doSomething();
    doSomethingElse();
}elseif($b){ # do add margin from braces; also ELSE and IF should be separate here
    try{
        nukeSaintPetersburg('😈');
    }finally{
        return PEACE;
    }
}

Switches

• break must be on same indentation level as the code of le case (not the case definiton itself)
• If there is no need to break a comment # NOTICE falling through must be places instead

# OK
switch($a) {
    case 1:
        echo $a;
        break;
    
    case 2:
        echo $a++;
        # NOTICE falling through
    
    default:
        echo "c";
}

# NOT OK
switch($a) {
    case 1:
        echo $a;
    break;
    
    case 2:
        echo $a++;
    
    default:
        echo "c";
}