mirror of
https://github.com/openvk/openvk
synced 2024-09-21 16:38:26 +03:00
277 lines
7.2 KiB
Markdown
277 lines
7.2 KiB
Markdown
# 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
|
|
<?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:
|
|
```php
|
|
# 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:
|
|
```php
|
|
# 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:
|
|
```php
|
|
# 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
|
|
```php
|
|
# 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.
|
|
```php
|
|
# 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:
|
|
```php
|
|
# 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
|
|
```php
|
|
# 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";
|
|
}
|
|
```
|