home chevron_right
Комментарии, стиль, API

Комментарии: краткие, на EN, в нижнем регистре; только по делуlink

В SF4-кодовой базе и в проектах на её основе комментарии лучше воспринимать как “подсказки по намерению”, а не как пересказ кода. Хороший комментарий отвечает на один из трёх вопросов:

  • почему сделано именно так (а не иначе),
  • какой контракт ожидается на входе/выходе,
  • какой крайний случай покрывается.

Если комментарий не добавляет смысла (например, “get config” над строкой $config = ...) — его лучше не писать: он устаревает быстрее кода и создаёт шум.

Рекомендации по формату:

  • язык: EN (чтобы код одинаково читался любой командой и не смешивались RU/EN в файлах),
  • стиль: lower case,
  • длина: 1–2 строки,
  • размещение: перед блоком/веткой, а не над каждой строкой.

Пример “по делу”:

<?php

declare(strict_types=1);

// cache result in session to avoid repeated iblock lookups per user
$iblockId = Iblock::getValue('catalog');

Пример “не по делу” (лучше убрать):

// get iblock id
$iblockId = Iblock::getValue('catalog');

Код-стайл: PSR-12; для логики Bitrix — D7 API; избегать старых APIlink

Для проекта на SF4 важно два уровня единообразия:

  1. внутренний стиль PHP-кода (читаемость, единый формат),
  2. единый подход к Bitrix API (как вы ходите в данные, как подписываетесь на события, как строите бизнес-логику).

PSR-12 задаёт “механическую” часть: отступы, скобки, структура классов/методов. Это особенно полезно в SF4-проектах, где рядом живут: шаблонный PHP, классы модуля и интеграционный код.

Для работы с Bitrix лучше в первую очередь использовать D7 API:

  • классы ядра и модулей (\Bitrix\Main\..., \Bitrix\Iblock\...),
  • ORM-таблицы там, где они доступны,
  • события и обработчики через современные механизмы.

При этом в SF4 ядре встречаются legacy-вызовы (например, CIBlockElement::GetByID, CIBlockSection::GetByID, CFile::GetFileArray). Это часть реализации, и с ней придётся сталкиваться при разборе ядра. Но в проектной логике имеет смысл придерживаться правила:

  • в своём коде — D7, где это реально возможно и удобно,

  • legacy — только когда:

    • нет прямого D7-аналога,
    • или требуется поведение, которое в legacy выражается проще и стабильнее.

Практическая рекомендация: не “переписывать” SF4 ядро под D7 в проекте — это относится к внутренностям. Но новые сущности и прикладной код в решении писать через D7, чтобы уменьшить технический долг.

Булевые: использовать 'Y'/'N' там, где это требуется Bitrix/SIMAIlink

В Bitrix и в SF4-логике многие режимы и параметры традиционно хранятся как строки 'Y' / 'N'. Это важно, потому что:

  • в конфигурациях и свойствах эти значения часто сериализуются в PHP-массивы;
  • часть проверок в коде делается строковыми сравнениями (=== 'Y');
  • UI-формы Bitrix обычно работают именно с 'Y'/'N'.

Поэтому правило простое:

  • если настройка/параметр относится к Bitrix/SF4 режимам — используйте 'Y'/'N',
  • не подменяйте это на true/false, чтобы не ловить “режим включён, но не сработал”.

Пример проверки режима (типовой паттерн SF4):

<?php

declare(strict_types=1);

use SIMAI\Main\Configuration\Property;

$isEditMode = Property::getValue(SF_SITE_DIR, 'edit_mode') === 'Y';

if ($isEditMode)
{
    // enable overlays / public editor tools
}