Стандарты разработки на платформе 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();?>
  

Отладка

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

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

• Воспользуйтесь модулем Bitrix Debug, GitHub.

Вывод в файл

• api_help

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:
  
  • CMain::AddHeadScript
  • CMain::SetAdditionalCSS
• Если файлы ресурсов подключены неправильно, высока вероятность, что браузеры начнут их активно кэшировать. Не забывайте про специализированные расширеня для браузеров:
  
  • Chrome Clear Cache
• НЕЛЬЗЯ вставлять код вызова компонента внутрь файла 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