Совместно с Александром Сербулом, руководителем направления контроля качества интеграции и внедрений 1С-Битрикс, подготовили список вопросов программисту для самопроверки при реализации задач разработки. Этот чек-лист прекрасно подходит для создания стандартов программирования в компании и поможет вхождению в коллектив новых сотрудников!
Написание кода
- Код оформлен по правилам, принятым в компании Правила составлены на основании стандарта PSR-2. Соблюдение данных правил позволяет производить однородный по структуре код, который проще сопровождать и развивать. Он корректно отображается в IDE, поддерживает их встроенный инструментарий.
- Названия классов: слова без пробелов и знаков, каждое новое слово с заглавной буквы (StudlyCaps)
- Названия методов: сбова без пробелов, с маленькой буквы, каждое последующее слово с большой (camelCase)
- Названия констант капсом с разделителями – нижнее подчеркивание
- Код структурирован. Отступы: 4 пробела
- Логические блоки отделены пустыми строками
- Открывающая{в классах и методах переносится на новую строку после названия, закрывающая}– на новую строку после «тела»
- Открывающая{в условиях и циклах не переносится на новую строку, закрывающая}– переносится
- Не располагать в троке более одного оператора
- Константы true, false и null должны быть в нижнем регистре
- Пробелы расставляются после запятых, но не до
- Пробелы расставляются до открывающей скобки и после закрывающей
- Использованы "говорящие" имена переменных, функций и так далее
- В названиях функций использованы префиксы: is (обозначение вопроса), get (получить значение), set (установить значение)
- Переменные, содержащие массивы начинаются с $ar; объекты - $ob Крайне важно при написании кода именовать все сущности таким образом, чтобы они помогали при прочтении понять смысл и логику происходящего. Соблюдение данного правила продемонстрирует уважение к коллегам, которые будут в дальнейшем сопровождать и развивать код, снизит трудозатраты на анализ и восприятие написанного
- Расставлены комментарии в достаточном для простого восприятия кода количестве
- Комментарий перед методом коротко и ёмко описывает его назначение, входные и выходные параметры. Комментарий должен погрузить читающего в инфополе того, что будет происходить в коде, не давая противоречивых сведений и двойных трактовок, потому что дальнейшее прочтение листинга будет происходить под призмой комментария.
- Комментарии к константам указывают их назначение и область применения
- Комментарии к условиям и циклам описывают суть происходящего в соответствующих блоках
- Комментарии к формулам описывают логику вычисления
- Комментарии к массивам описывают структуру массива
и так далее
Работа с Bitrix Framework. Общее
- Не использованы прямые запросы к БД В большинстве случаев можно обойтись без прямых запросов к базе данных. Это позволит избежать множества ошибок, нарушения безопасности кода, сохранения структуры данных и так далее. API Битрикса очень богат по возможностям. И если чего-то не нашли в документации, загляните на www.bxapi.ru или спросите у коллеги. Использование прямых запросов к базе данных при работе с модулями Битрикс в любом случае будет ошибкой. Допускается только для старших разработчиков после обоснования и защиты решения.
- Ядро не модифицировалось Модификация ядра приводит к потере контроля над функционированием системы. Любое обновление может привести к выходу её из строя. Снятие модулей ядра с обновлений не допускается
- Для кастомизации используется только папка /local/ Битрикс даёт разнообразные возможности для корректной кастомизации продукта. Однако, чтобы не забивать голову порядком применения компонент, шаблонов и так далее, необходимо все изменения и наработки выносить в папку /local/ и только. Это позволит проще ориентироваться в файловой структуре, меньше времени тратить на поиск нужного элемента, а также упростить перенос изменений между серверами разработки, тестирования и эксплуатации.
- Все фразы - через языковые файлы Использование языковых файлов помогает избежать проблем с кодировками и упрощает локализацию
- Для выполнения задач по расписания используются Агенты Агенты нагляднее, ими проще управлять, они заставляют оформлять код в метод, автоматически подключают служебные скрипты Битрикса. Другими словами, упрощают жизнь разработчику и позволяют избежать проблем с отладкой. Конечно, Агенты должны выполняться на CRONе, но этот пункт не является частью данного чек-листа
Про написание скриптов
- Передаваемые скриптам параметры очищаются и верифицируются Разработчик должен понимать, какие данные ожидает получить его код в тех или иных параметрах. Если параметры передаются странице извне, то они должны обязательно проходить верификацию: очищать от лишних пробелов, проверяться на соответствие типа данных, приводиться в требуемый формат и так далее. В случае, если после верификации получается недопустимое значение, необходимо задать для параметра значение по-умолчанию. Данное правило позволяет избавить код от уязвимостей и непредсказуемого результата в случае некорректности передаваемых данных
- Страницы ajax-обработчиков и отдельных скриптов не запускаются по прямому запросу Основное правило: обработчик запроса должен иметь возможность вызвать только тот скрипт, для которого этот обработчик написан. Иначе, появляется возможность для парсинга данных и разного рода атак
- В коде не "зашиты" значения параметров, используются только переменные/константы, вынесенные в верхнюю часть кода и подписанные комментарием Любой код должен иметь хорошую транспортабельность. То есть его должно быть просто адаптировать под схожую задачу в другом проекте. В случае с компонентами, все их настройки выносятся в параметры, что позволяет без труда выбрав необходимые параметры добиться работы компонента на любом схожем по структуре данных проекте. В случае с отчуждаемым кодом, данные параметры должны быть вынесены в верхнюю часть листинга и описаны по назначению. В дальнейшем такой код будет проще как адаптировать под новый проект, так и преобразовать в компонент.
- Код разбит на логические части в следующем порядке: подключение библиотек, установка констант, установка и верификация параметров, классы и функции, код Данная структура кода позволит быстрее в нём ориентироваться, а также с наименьшими затратами преобразовать его в компонент
- Код сначала собирает все необходимые данные в массив, а потом на основании массива строит вывод данных в HTML Такой порядок работы с данными позволяет с большим удобством управлять их выводом. Кроме того, именно по такому принципу действуют компоненты Битрикс, что существенно упрощает дальнейшее преобразование кода в компонент
- Перед использованием API проверяется подключение соответствующего модуля. При подключении модулей отрабатывает вариант, что модуль не установлен Если используются классы не подключенного модуля, на странице возникнет фатальная ошибка. Правило важно соблюдать ещё и потому, что разрабатываемый код может находиться на страницах с различным составом подключенных модулей. На этапе разработки ошибка может и не возникнуть из-за того, что в какой-либо части страницы подключается требуемый модуль без нашего участия. Но в других условиях этот же код приведёт к ошибке, что недопустимо.
- Используется кеширование. Не кешируются лишние данные Кеширование способствует минимизации нагрузки на базу данных, повышению производительности проекта и, как следствие, удовлетворённости его пользователей.
- Нет запросов в циклах Запросы в циклах приводят к лавинообразному увеличению нагрузки на базу данных при увеличении числа проходов. При тестировании нагрузку можно не выявить из-за небольшого объёма тестовых данных, а в реальных условиях данная структура может привести к критическим последствиям.
Пример того, как не нужно писать код:$rsRes = CIBlockElement::GetList(array(), array(“IBLOCK_ID” => 1)); while ($arRes = $rsRes->GetNetx()){$userID = $arRes[“CREATED_BY”]; $rsUser = CUser::GetByID($userID); if($arUser = $rsUser->GetNext()){//…}}
При 10 элементах в инфоблоке с ID = 1, код выполнит 11 запросов. При 1000 – 1001. - При выполнении страниц и вспомогательных скриптов проекта отсутствуют предупреждения (E_WARNING) PHP
- Разметка, возвращаемая компонентом и включаемой областью, должна возвращать целостный html-блок с закрытыми тэгами Наш код должен быть легко отчуждаем и переносим. «Рваный» HTML приводит к проблемам с вёрсткой, сложностям в сопровождении и шаблонизации решения.
- Если логика требует повторения части кода, она выносится в функцию В таком случае, код проще развивать и корректировать. Не требуется вносить правки в нескольких однотипных частях, достаточно изменить их в одном месте. А также корректно оформленный в метод блок кода намного удобнее тиражировать.
