▼

четверг, 2 октября 2014 г.

Стандарты разработки на платформе 1С-Битрикс

(с) https://github.com/uniplug/bitrix-style-guide - оригинал данного руководства. Возможно кому-то окажется полезным.

В данном руководстве описаны рекомендуемые техники при разработке на платформе 1С-Битрикс / 1C-Bitrix (далее - Битрикс). Если вы заметили ошибку и хотите внести исправление или дополнение, пожалуйста, не стесняйтесь делать pull request или связываться напрямую.
Приветствуется любая помощь.

PHP

  • Код PHP должен быть написан в соответствии со стандартом PSR-1.
  • Стиль написания кода должен соответствовать стандарту PSR-2.
  • В конечном итоге придерживаемся правил форматирования (ядро D7) от разработчиков системы.

Оформление исходного кода

  • Используйте кодировку UTF-8 без BOM для файлов с исходным кодом.
  • Используйте Unix-style окончания строк LF. Никаких CR+LF.
  • Используйте сокращенные теги <? и <?=.
    // bad
<?php echo .. ?>

// good
<?= .. ?>
  • Используйте ТАБ для каждого отступа. Никаких пробелов для блоков кода.

Общие положения

  • При добавлении кода в файл init.php группируйте код в классы и выносите их в отдельные файлы.
  • При подключении файлов используйте только функции Битрикса. Цитата:
    Поддержка Bitrix Framework русских (и прочих) символов в названиях публичных файлов накладывает определённые ограничения на работу: недопустимы прямые вызовы
    • к файлам, имена которых выбираются пользователями,
    • к папкам, имена которых выбираются пользователями,
    • к файлам и папкам, которые могут лежать в папках, имена которых выбираются пользователями. Недопустимы вызовы любых прямых методов работы с файловой системой: include, require, fopen, filesize, unlink, file_exists и т.д. http://dev.1c-bitrix.ru/api_help/main/reference/cbxvirtualio/index.php
    init.php
    // bad
// SomeClass
include('../some_file.php');

//good
// SomeClass
$APPLICATION->GetFileContent('../some_file.php');
  • Не используйте цифровые значения в GetList, GetByID и схожих методах, которые принимают различные ID. Создайте файл со всеми необходимыми константами и используйте их имена. 
    // bad
$comments = CIBlockElement::GetList(Array(), Array("IBLOCK_ID" => 12));
    1. У каждой константы должно быть говорящее имя и комментарий.
    2. Файл constants.php:
      // ИБ с комментариями пользователей
const COMMENTS_IBLOCK_ID = 12;
    3. Подключите этот файл в init.php
      //Константы проекта
$APPLICATION->GetFileContent($_SERVER["DOCUMENT_ROOT"] . '/bitrix/php_interface/includes/constants.php');
    4. Используйте константу
      $comments = CIBlockElement::GetList(Array(), Array("IBLOCK_ID" => COMMENTS_IBLOCK_ID));
  • Используйте Bitrix IBlock Tools, обсуждение.
  • При выборках данных (например, GetList) обязательно указывайте поля, которые нужны для дальнейших манипуляций, кроме случаев, когда нужны все поля:
    // good - Обязательно указывайте поля для выборки
$arSelect = Array("ID", "NAME", "DATE_ACTIVE_FROM");
...
$res = CIBlockElement::GetList(Array(), $arFilter, false, Array(), $arSelect);
  • При необходимости выбрать несколько элементов по ID, обязательно используйте GetList вместо GetByID:
    // bad
$element1 = CIBlockElement::GetByID(1);
$element2 = CIBlockElement::GetByID(2);

// good
$elements = CIBlockElement::GetList(Array(), Array(1, 2));
  • Не используйте прямые запросы к базе данных, вся работа только через API.
  • Если к файлу не предусмотрен прямой доступ через WEB, в первой строке файла добавьте:
    <?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();?>

Отладка

Важно
Логирование замедляет работу системы и может являться брешью в безопасности

Вывод на экран

Вывод в файл

  1. Определите константу LOG_FILENAME в файле /bitrix/php_interface/dbconn.php, задавая путь к лог-файлу за пределами DOCUMENT_ROOT.
    // определяем константу LOG_FILENAME, в которой зададим путь к лог-файлу
define("LOG_FILENAME", $_SERVER["DOCUMENT_ROOT"]."/../log.txt");
  2. Отправьте сообщение в лог
    AddMessage2Log("Произвольный текст сообщения", "module_id");
    Пример:
    AddMessage2Log( print_r($arResult, true) );

SQL

  • Определите переменную DBDebugToFile для логирования всех SQL запросов.
    $DBDebugToFile = true;

Работа с компонентами

  • Шаблонам компонентов давайте осмысленные названия и в каждом проекте придерживайтесь общего стиля. Например, Раздел/страница_сайта.Название.Тип
    Примеры:
    • index.user.auth
    • profile.orders.list
    • cart.products.additional
  • Стандартные компоненты не модифицируются. Если возникнет такая необходимость — создайте копию компонента в своем пространстве имен в каталоге /bitrix/components/.
  • РЕКОММЕНДУЕТСЯ все шаблоны компонентов сохранять в шаблоне .default в каталоге /bitrix/templates/.default/.
  • НЕ РЕКОМЕНДУЕТСЯ делать любые манипуляции с данными в файле template.php. При необходимости правки логики стандартных компонентов, но недостаточной для того, что делать свой используются файлы result_modifier.php и component_epilog.php
  • РЕКОМЕНДУЕТСЯ использовать файлы style.css и script.js в шаблонах только если они переопределяют стандартное поведение схожих элементов. РЕКОМЕНДУЕТСЯ оставить комментарий об этой особенности.

Кэширование

  • Кэширование компонентов не отключается. Практически не существует задач, которые нельзя решить с включенным кэшированием.
    Исключение:
    • Во время разработки полностью отключайте кэширование - это съэкономит вам много времени.
  • Подключайте js и css файлы только через предназначенный для этого API:
  • Если файлы ресурсов подключены неправильно, высока вероятность, что браузеры начнут их активно кэшировать. Не забывайте про специализированные расширеня для браузеров:
  • НЕЛЬЗЯ вставлять код вызова компонента внутрь файла template.php другого компонента.
    Это противоречит идеологии разделения даннах и представления (см. выше) и влечет двойное кэширование.

Работа с шаблонами

  • РЕКОМЕНДУЕТСЯ использовать минимальное количество шаблонов.
  • РЕКОМЕНДУЕТСЯ подключать header.php и footer.php из одного места для всех шаблонов, если это позволяет дизайн и верстка.
  • РЕКОМЕНДУЕТСЯ общие картинки, скрипты и стили шаблонов сохранять в одном месте, например, в /bitrix/templates/.default/.

Структура шаблона

  • В каталоге шаблона остаются только необходимые для Битрикс файлы - header.php, footer.php, styles.css и т.д.
  • Включаемые файлы располагаются в каталоге includes
  • Все дополнительные файлы (скрипты, изображения и т.д.) располагаются в каталоге assets:
    • js - свои скрипты и однофайловые библиотеки
    • css - свои стили и однофайловые библиотеки
    • images - изображения, спрайты, иконки
    • fonts - шрифты
    • остальные библиотеки и фреймворки располагаются в каталогах, названия которых совпадают с названием и версией библиотеки, при этом сохраняется внутренняя структура дистрибутива.
      • Документацию, примеры и доп. файлы можно удалить.
Пример:
/local/templates/<название_шаблона>/
├── header.php
├── footer.php
├── styles.css
├── templaye_styles.css
│
├── components/
|   ├── ..
│
├── assets/
│   ├── js/
|   |   ├── custom.js
|   |   ├── jquery.dataAttributeEvents.js
│   |
│   ├── css/
|   |   ├── ..
│   |
│   ├── images/
|   |   ├── ..
│   |
│   └── bootstrap-3.0.0/
│       ├── js/
│       ├── css/
  ...

Работа с инфоблоками

  • Названия свойств инфоблоков должны быть:
    1. в верхнем регистре;
    2. осмысленными (используйте связку сущность_наименование);
    3. слова разделаются подчеркиванием.
    Пример:
    • Имя пользователя: USER_NAME
    • Валюта заказа: ORDER_CURRENCY
    • Список заказов: ORDER_LIST
на

Комментариев нет :

Отправить комментарий