Документация InstantCMS

для администраторов и разработчиков

Инструменты пользователя

Инструменты сайта


dev:php-agreement

Соглашение по стилю программирования PHP

При разработке дополнений для InstantCMS мы рекомендуем придерживаться следующих правил при написании PHP кода. Такой единый подход сформирует последовательный стиль программирования, код будет чистым и легко читаемый с первого взгляда.

Именование

Общие положения по именованию

Весь текст в коде должен быть на английском языке (исключая комментарии). Не допускается именовать переменные/классы/… транслитом. Не рекомендуется использовать сокращения слов. Аббревиатуры должны также переводиться на английский.

Переменные и функции, определяемые пользователем

  • Имена в нижнем регистре, слова разделяются через нижнее подчеркивание;
  • Логические (boolean) начинаются с префикса is_;
  • Имена массивов переменных пишутся в множественном числе или оканчиваются на _list;
  • Имя должно максимально точно описывать ее содержание.

Примеры:

$var, $users_count, $is_active, $articles, $items_list

Классы

  • Имена в lowerCamelCase - первая буква маленькая, каждое следующее слово с большой буквы;
  • Свойства классов именуются как обычные переменные;

Методы классов

  • Методы классов именуются по тем же правилам, что и сами классы (lowerCamelCase);
  • В имени метода сначала указывается действие (add, get, remove), затем объект (Item, Article, User);
  • Методы классов должны всегда определять свою область видимости с помощью одного из префиксов private, protected или public;
  • Если использование метода предполагается только внутри объекта/класса не стоит пренебрегать указанием области видимости, используя ключевые слова private и protected.

Примеры:

public function addArticle(){}
public function getListItems(){}
private function removeOldLog(){}

Файлы

  • Имена файлов и каталогов всегда в нижнем регистре;
  • Слова разделяются нижним подчеркиванием;
  • Пробелы запрещены. Любой файл, содержащий PHP-код (кроме html-шаблонов) должен иметь расширение .php.

Настройки отступов и табуляции в IDE

Настройте ваш редактор PHP на размер табуляции отступов в четыре пробела. При сохранении файла желательно, чтобы IDE автоматически удаляла концевые пробелы строк.

Структура кода

Окончание файла

В конце файла всегда должен ставиться перенос строки.

Фигурные скобки

Фигурные скобки после названия классов, методов, функций, логических операторов и т.п. всегда пишутся на той же строке.

Теги <?php

Короткие теги <? .. ?> запрещены. Для файлов, содержащих только PHP-код, закрывающийся тег (?>) не разрешен. Он не требуется синтаксисом PHP. Это предотвращает от случайного включения в вывод конечных пробелов.

Минимальная вложенность

Везде где можно избавиться от вложенности фигурных скобок - нужно от нее избавляться. В первую очередь касается конструкций if .. else. Если нужно выполнить блок кода если условие выполняется, то нужно делать так:

Хорошо:

if (!$is_good) { return false; }
 
doSomething();

Хорошо потому, что сразу видно что будет, если условие не выполняется.

Плохо:

if ($is_good) {
    doSomething();
} else {
    return false;
}

Плохо потому, что если внутри блока много кода, то чтобы увидеть else нужно скроллить. Плюс непонятно сразу, есть ли там вообще else.

Кроме того, если в логических выражениях идет обращение к каким-то функциям или методам, в которых скрипт неочевидно «умирает» необходимо подставлять return, например:

плохо:

if ($is_good) {
    doSomething();
} else {
    return false;
}
function doSomething(){ die('cms is die'); }

хорошо:

if ($is_good) {
    return doSomething();
} else {
    return false;
}
function doSomething(){ die('cms is die'); }

Размер функций/методов

Функция или метод должна выполнять одну атомарную задачу. Поэтому, если в функнцию заложено слишком много логики, стоит ее разбить на несколько.

Например, в функции addItem нам нужно сгенерировать slug (урл записи). Сам процесс генерации можно описать и в методе addItem, а можно вынести в отдельный метод. Второй вариант предпочтительней, т.к. у нас потом может появиться метод updateItem, где потребуется вновь процесс генерации slug. Мы конечно можем копировать код генерации из метода в метод, однако это нерационально и усложнит последующее обслуживание.

Операторы

Операторы должны отбиваться пробелами с двух сторон:

$a = 1;
$b == 2;
$c > 3;
$d || 4;

Строковые литералы

Когда строка является литеральной (не содержит подстановок переменных), для ее обрамления должны использоваться апострофы или «одинарные кавычки»:

$a = 'ICMS example string';

Когда строка литералов сама содержит апострофы, разрешается для обрамления строки использовать «двойные кавычки». Это особенно актуально для SQL-запросов:

$sql = "SELECT `id`, `email` from `cms_users` WHERE `email`='{$email}'";

Синтаксис выше является более предпочтительным, чем экранирование апострофов.

dev/php-agreement.txt · Последние изменения: 21.09.2016 19:53 — fuze