Правила и рекомендации по именованию

Внутренняя логика фреймворка опирается на ряд соглашений об именовании (файлов, классов, таблиц), несоблюдение которых приведет к неработоспособности приложения, поэтому соблюдение правил именования является одним из краеугольных камней при разработке приложений Вебасист и является обязательным.

Кроме обязательных правил в настоящий раздел включены рекомендации, носящие необязательный характер.

База данных

Таблицы

Обязательное правило: названия всех таблиц приложения должны начинаться с идентификатора приложения (APP_ID), отделенного символом подчеркивания.

Рекомендация: таблицы сущностей, например, для хранения сообщений в гостевой книге, стикеров, файлов и т.д., рекомендуется называть в единственном числе.

Примеры:

guestbook_message — таблица хранения сообщений в приложении guestbook
stickies_sticky — таблица хранения стикеров в приложении stickies
stickies_sheet — таблица хранения листов в приложении stickies

Рекомендация: таблицы связей, а так же таблицы, хранящие дополнительные данные, рекомендуется именовать по следующему правилу:
Название таблицы формируется из двух слов (в дополнение к обязательному префиксу APP_ID), разделенных символом подчеркивания - название главной сущности в единственном числе плюс второстепенная сущность во множественном числе (при наличии такой формы в названии сущности).

Примеры:

Таблица для хранения email-ов контактов.
wa_contact_emails — связь один ко многим, один контакт — несколько email

Поля

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

Примеры:

id
name
create_datetime

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

create_datetime
edit_datetime

Рекомендация: поля внешних ключей рекомендуется именовать следующим образом: название таблицы (без префикса) на которую ссылается поле, далее название соответствующего поля в этой таблице.

Примеры:

contact_id — ссылка на поле id в таблице контактов (wa_contact.id)
order_id — id заказа

Там где это необходимо, и для большей понятности, можно добавлять к такому имени поля смысловой префикс.

Например:

actor_contact_id — id контакта, совершившего действие
assigned_contact_id — id контакта, назначенного на выполнение задания и т.д.

Классы, методы и переменные PHP

Наименование классов и методов

Обязательное правило: названия всех классов приложения должны начинаться с идентификатора приложения (APP_ID). Это необходимо, чтобы не возникало конфликтов имён между классами разных приложений.

Обязательное правило: для именования классов и методов необходимо использовать так называемый «горбатый стиль»:
Слова в названии пишутся слитно (без символа-разделителя), первое слово (для классов - APP_ID) с маленькой буквы, остальные с большой.

Пример:

<?php

class filesFile
{
    public function getInfo() 
    {
        ...
    }
    ...
}

Именование PHP-файлов классов

Классы PHP подгружаются системой при выполнении скриптов с помощью механизма Autoload. Для того, чтобы механизм подгрузки смог найти нужный php-файл необходимо придерживаться определенных правил для именования файлов классов.

Обязательное правило: все файлы классов должны находиться внутри подпапки lib в каталоге приложения.

Обязательное правило: название файла класса должно иметь следующий формат: {НАЗВАНИЕ_КЛАССА}.class.php. Например, если класс называется contactsCollection, то его файл должен называться contactsCollection.class.php.

Обязательное правило: для файлов экшенов, контроллеров и моделей существует дополнительный формат именования, который рекоммендуется использовать: если в названии класса содержится суффикс Actions, Action, Controller или Model, то название файла класса должно иметь следующий формат: {НАЗВАНИЕ_КЛАССА_БЕЗ_СУФФИКСА}.{суффикс}.php ({суффикс} пишется строчными буквами). Несколько примеров:

Класс contactsGroupsSaveAction — файл contactsGroupsSave.action.php
Класс contactsGroupsActions — файл contactsGroups.actions.php
Класс contactsGroupsController — файл contactsGroups.controller.php
Класс contactsRightsModel — файл contactsRights.model.php

Именование классов и методов контроллеров и экшенов

Логика приложения, живущая в слое контроллеров, организована в двухуровневую иерархию «модуль/действие» (MODULE/ACTION). Правила маршрутизации задают соответствие между URL запроса и парой модуль+действие. Т.е. каждый запрос по сути запускает выполнение определенного действия внутри определенного модуля.

Механизм маршрутизации определяет названия модуля и действия (действие может быть не указано, в этом случае система запустит действие по умолчанию). Для того, чтобы система смогла определить какой метод какого класса необходимо вызвать для обработки поступившего запроса необходимо придерживаться следующих правил именования классов и методов контроллеров.

Обязательное правило: название класса и метода для обработки запроса должны соответствовать правилам, по которым система ищет класс и метод для исполнения. Поиск производится в следующем порядке (конкатенация строк при построении названия класса производится в «горбатом» стиле без разделителей):

Первым ищется класс с названием {APP_ID}{MODULE}{ACTION}Controller или, если не был указан ACTION, {APP_ID}{MODULE}Controller.
Если такой класс найден, то создается экземпляр этого класса и вызывается его метод execute, то есть это "стартовая точка" контроллера этой страницы.
Если класс наден не был, то ищется класс с названием, построенным по другому правилу - {APP_ID}{MODULE}Actions.
Если такой класс найден, то создается новый экземпляр и вызывается метод {ACTION}Action, либо метод DefaulAction, если ACTION не был указан.
Подобные контроллеры, методы которых - это отдельные экшены, популярны во многих фреймворках.
Если второй вариант класса также не был найден, ищется третий вариант с названием {APP_ID}{MODULE}{ACTION}Action или, если не указан ACTION, {APP_ID}{MODULE}Action.
Если такой класс найден, то создается его экзепляр и вызывается метод execute.
Если ни один класс не найден, то отдается ошибка 404.

Примеры допустимых соответствий пар модуль + действие и названий классов и методов.

Приложение myblog, модуль mail, действие не указано:

myblogMailController->execute()
myblogMailActions->defaultAction()
myblogMailAction->execute()

Приложение myblog, модуль mail, действие test:

myblogMailTestController->execute()
myblogMailActions->testAction()
myblogMailTestAction->execute()

Подробнее система маршрутизации рассматривается в разделах «Маршрутизация в бекенд» и «Маршрутизация во фронтенд».

Именование файлов шаблонов

Каждый шаблон жестко привязан к конкретному действию конкретного модуля.

Механизм определения шаблона для рендеринга опирается на названия модуля и действия.

Обязательное правило: файл шаблона ищется по следующему пути внутри файловой структуры приложения: templates/actions/{MODULE}/{MODULE}{ACTION}.html

Например, для модуля mail и действия test система применит в качестве шаблона файл templates/actions/mail/mailTest.html

Обязательное правило: для случаев, когда ACTION не был указан, правила именования шаблона зависят от типа класса экшена:

Для экшенов, реализуемых методом defaultAction файл шаблона должен называться {MODULE}Default.html
Для экшенов, реализуемых методом execute файл шаблона должен называться {MODULE}.html

Подробнее о типах классов экшенов см. раздел «Экшены и контроллеры».

Рекомендации по стилю форматирования PHP-кода

Рекомендация: при разработке приложений (особенно при командной разработке), рекомендуется придерживаться единого стиля форматирования кода. Мы рекомендуем придерживаться стиля, применяемого в коде фреймворка и приложений Вебасист:

<?php //использовать только такой открывающий тег и никакой другой

/**
* @desc Всегда оставлять комментарии к своим классам в формате PhpDOC
*/
class CodingStyle //классы называть по правилу «верблюжьего горба»
{ //открывающую фигурную скобку в начале класса ставить с НОВОЙ строки

    //табуляция заменяется 4 пробелами
    //кодировка - UTF-8
    //переносы строк UNIX, то есть \n, а не \r\n

    /**
    * @desc формат названий переменных должен отличаться от формата названий методов
    * в названиях переменных использовать только маленькие буквы и разделять слова подчеркиванием
    */
    public $is_right;

    /**
    * @desc К методам и функциям писать комментарии
    * @param $code int - описывать входные данные
    * @return boolean - описывать выходные данные
    */
    public function doIWriteValidCode($code) //методы называть по принципу «верблюжьего горба»
    { //открывающую фигурную скобку в начале метода ставить с НОВОЙ строки

        //внутри методов и функций писать комментарии ТОЛЬКО в таком виде и не использовать
        //многострочное оформление даже если комментарии на несколько строк

        $this->is_right = false; //символы +-=*/{} и пр. обязательно отделять пробелами


        if (! $code) { //любую открывающую скобку внутри методов ставить на ТОЙ ЖЕ строке
            //нет кода - нет проблемы.
            $this->is_right = true; //использовать скобки, ДАЖЕ если оператор в конструкции один
        } else { //else/elseif писать на ТОЙ ЖЕ строке, что и закрывающая скобка оператора if
            $this->is_right = $this->checkMyCode($code);
        }

        return $this->is_right;
    }

    /**
    * @desc Составлять описание, даже если название метода говорит само за себя
    */
    public function checkMyCode($code)
    {
        return false; //Закон природы - мы всегда найдем к чему придраться, какой бы код ни был
    }
}
//в конце файла закрывающий тэг не ставить

webasyst alpha

Правила и рекомендации по именованию

База данных

Таблицы

Поля

Классы, методы и переменные PHP

Наименование классов и методов

Именование PHP-файлов классов

Именование классов и методов контроллеров и экшенов

Именование файлов шаблонов

Рекомендации по стилю форматирования PHP-кода

webasyst ^alpha