Стандарти кодування Phalcon

Останнє оновлення: 2019-07-04

Phalcon is written in Zephir, a language that the Phalcon Team invented and is actively developing. Тому не існує встановлених стандартів кодування, яких можуть дотримуватись розробники, якщо бажають.

У цьому документі ми розкриємо стандарти кодування, які використовує Phalcon для редагування файлів Zephir. The coding standard is a variant of PSR-12 developed by PHP-FIG

Файли

Файли мають використовувати лише UTF-8 без BOM.
Імена файлів повинні називатися по принципу StudlyCaps (великі літери виділяють істотні складові суті файла).
Всі файли повинні використовувати кінець рядка за правилами Unix LF (linefeed).
Всі файли мають закінчуватися одним пустим рядком.
Folders are also named StudlyCaps and the folder/sub-folder tree follows the namespace of the class.

phalcon/Acl/Adapter/Memory.zep

namespace Phalcon\Acl\Adapter;

use Phalcon\Acl\Adapter;

class Memory extends Adapter
{

}

Код має використовувати 4 пробіли для відступу, а не таби.
Lines should be 80 characters or fewer. Жорсткий ліміт на довжину рядка 120 символів.
Має бути по одному порожньому рядку після декларування простору імен та після блоку оголошень використання “use”.
У кінці непорожніх ліній не повинно бути пробілів.
Порожні лінії можуть бути додані для поліпшення читабельності та виділення пов’язаних блоків коду.
У кожному рядку повинно бути не більш одного твердження.

Класи

Імена класів повинні бути оголошені по принципу StudlyCaps.
Відкриваючі дужки класів повинні розташовуватися у наступному рядку, а закриваючі дужки - у наступному рядку після тіла.
Абстрактні класи повинні бути попередньо визначені за допомогою Abstract
Інтерфейси повинні мати суфікс Interface

Constants

Класові константи мають бути задекларовані у верхньому регістрі з роздільниками підкреслення.
Константи класу повинні з’явитись на початку вмісту класу.
Константи класу потрібно відсортувати по алфавіту за іменем.

namespace Phalcon\Acl;

class Enum
{
    const ALLOW = 1;
    const DENY  = 0;
}

Властивості

Властивості класу повинні бути оголошені у верблюжому (горбатому) регістрі.
Властивості класу мають бути відсортовані в алфавітному порядку за назвою.
Завжди, коли це можливо, властивості повинні мати значення за замовчуванням.
Коли це можливо, властивості повинні мати док-блок, який визначає їх тип за допомогою декларації @var.
Властивості не повинні мати підкресленням _ на початку назви. Єдиний виняток допускається, якщо назва властивості є зарезервованим ключовим словом, наприклад default, namespace і т. д.

namespace Phalcon\Acl\Adapter;

use Phalcon\Acl\Adapter;

class Memory extends Adapter
{
    /**
     * @var string | null
     */
    protected activeKey = "" { get };
}

Методи

Імена методів мають бути задекларовані у верблюжому (горбатому) регістрі.
Методи мають бути відсортовані в алфавітному порядку і починатись з визначення їх видимості. Порядок є таким: public, protected і private. __construct, якщо визначено, має бути вгорі вмісту класу.
Назви методів не повинні містити підкреслювання _ на початку.
Всі методи повинні мати тип повернення. Якщо метод не повертає нічого, він має бути позначений як void
Відкриття дужок методів має відбуватися на наступному рядку після їх декларування, а закриття дужок - на наступному рядку після їх тіла.
Видимість має бути оголошена у всіх властивостях та методах; abstract та final мають бути оголошені перед видимістю; static повинна бути оголошена після видимості.

abstract public function getElement() -> var;

final public function getElement() -> var;

public static function getElement() -> var;

Ключові слова контрольної структури повинні мати один пробіл після них, а виклики метода та функції навпаки не повинні.
Відкриття дужок для контрольних структур має відбуватися в тому ж рядку, а закриття дужок має відбуватися у наступному рядку після тіла.
Контрольні структури, такі як if не повинні містити круглих дужок навколо умови, якщо тільки це не складна умова.

if typeof variable === "array" {

}

Аргументи методу

У списку аргументів не має бути пробілу перед кожною комою, але після кожної коми має бути один пробіл.
Кожен метод повинен мати свій тип оголошений перед ним
Аргументи методу зі значеннями за замовчуванням повинні йти в кінці списку аргументів.

public function setElement(string! name, var value) -> void;

Списки аргументів МОЖНА розділяти на кілька рядків, де кожен наступний рядок відступає на один крок. Якщо так робити, то перший елемент списку повинен бути у наступному рядку, і має бути лише один аргумент на рядок.