Skill v1.0.1
Automated scan100/100+1 new
version: "1.0.1" name: coding-standards description: "MUST use WHEN пишешь или ревьюишь BSL-код. Provides стандарты именования, структуру модулей, типовые антипаттерны и рекомендации ИТС для платформы 1С:Предприятие." alwaysApply: false
Стандарты кодирования BSL (1С)
Правило 1: Именование переменных — CamelCase на русском языке
Стандарт ИТС: «Тексты модулей» — имена на русском, ВерблюжийРегистр.
| Элемент | Формат | Пример | |
|---|---|---|---|
| Переменная | СуществительноеИлиФраза | КоличествоСтрок, ДатаНачалаПериода | |
| Процедура | ГлагольнаяФраза | ЗаполнитьТабличнуюЧасть, УстановитьОтбор | |
| Функция | СуществительноеИлиВопрос | ПолучитьСписокДокументов, ЭтоНовый | |
| Булева переменная | Утвердительная форма | ЭтоНовый, РазрешеноРедактирование, ЕстьОшибки | |
| Параметр | КакПеременная | ДокументСсылка, РежимОткрытия |
Процедура ЗаполнитьТабличнуюЧастьТовары(ДокументОбъект, ДанныеЗаполнения)КоличествоСтрок = ДанныеЗаполнения.Количество();ЕстьОшибки = Ложь;Для Каждого СтрокаДанных Из ДанныеЗаполнения ЦиклНоваяСтрока = ДокументОбъект.Товары.Добавить();НоваяСтрока.Номенклатура = СтрокаДанных.Номенклатура;НоваяСтрока.Количество = СтрокаДанных.Количество;КонецЦикла;КонецПроцедуры
Правило 2: Структура модуля — секции интерфейса и реализации
Стандарт ИТС: «Структура модуля» — области (#Область) в определённом порядке.
Порядок секций общего модуля
#Область ПрограммныйИнтерфейс// Экспортные процедуры и функции — публичный API модуля.Функция ПолучитьКурсВалюты(Валюта, ДатаКурса) Экспорт// ...КонецФункции#КонецОбласти#Область СлужебныйПрограммныйИнтерфейс// Экспортные процедуры для вызова только из других модулей данной подсистемы.Функция ПересчитатьКурсВнутренний(ПараметрыПересчета) Экспорт// ...КонецФункции#КонецОбласти#Область СлужебныеПроцедурыИФункции// Внутренняя реализация. Не экспортные.Функция СформироватьЗапросКурса(Валюта, Дата)// ...КонецФункции#КонецОбласти
Порядок секций модуля объекта
#Область ОписаниеПеременныхПерем МассивИзменённыхРеквизитов;#КонецОбласти#Область ОбработчикиСобытийПроцедура ОбработкаЗаполнения(ДанныеЗаполнения, ТекстЗаполнения, СтандартнаяОбработка)// ...КонецПроцедурыПроцедура ПередЗаписью(Отказ)// ...КонецПроцедуры#КонецОбласти#Область СлужебныеПроцедурыИФункции#КонецОбласти#Область ИнициализацияМассивИзменённыхРеквизитов = Новый Массив;#КонецОбласти
Правило 3: Директивы компиляции — &НаКлиенте, &НаСервере, &НаСервереБезКонтекста
При вызове &НаСервере платформа сериализует весь контекст формы туда-обратно. &НаСервереБезКонтекста передаёт только параметры — радикально меньше трафика.
| Директива | Где выполняется | Доступ к данным формы | Когда использовать | |
|---|---|---|---|---|
&НаКлиенте | Клиент (тонкий/веб) | Да (клиентская копия) | Интерактивная логика: диалоги, навигация | |
&НаСервере | Сервер | Да (полный контекст формы) | Нужен доступ к реквизитам формы + БД | |
&НаСервереБезКонтекста | Сервер | Нет | Запросы к БД, вычисления без данных формы | |
&НаКлиентеНаСервереБезКонтекста | И клиент, и сервер | Нет | Чистые вычисления, валидация без БД |
&НаКлиентеПроцедура НоменклатураПриИзменении(Элемент)ДанныеНоменклатуры = ПолучитьДанныеНоменклатуры(Элементы.Товары.ТекущиеДанные.Номенклатура);ЗаполнитьСтрокуТоваровНаКлиенте(ДанныеНоменклатуры);КонецПроцедуры&НаСервереБезКонтекстаФункция ПолучитьДанныеНоменклатуры(НоменклатураСсылка)Возврат Новый Структура("ЕдиницаИзмерения, Цена, СтавкаНДС",НоменклатураСсылка.ЕдиницаИзмерения,НоменклатураСсылка.Цена,НоменклатураСсылка.СтавкаНДС);КонецФункции
Правило 6: Не затеняйте глобальный контекст
Локальная переменная с именем глобальной коллекции скрывает менеджер — дальше в коде обращения к нему дадут ошибку.
// Правильно — конкретное имяМассивДокументовКОбработке = Новый Массив;СправочникНоменклатура = Справочники.Номенклатура;
Список зарезервированных имён (не использовать для переменных)
Документы, Справочники, Регистры, Перечисления, ПланыОбмена, ПланыВидовХарактеристик, ПланыВидовРасчета, ПланыСчетов, БизнесПроцессы, Задачи, Обработки, Отчеты, Константы, ПараметрыСеанса, РегистрыСведений, РегистрыНакопления, РегистрыБухгалтерии, РегистрыРасчета
Правило 7: Конкатенация строк — не используйте «+» в циклах
В BSL строки иммутабельны. Строка1 + Строка2 в цикле из N итераций даёт O(N^2) по памяти и времени — каждая итерация копирует всё предыдущее.
Стандарт ИТС: «Эффективная работа со строками».
// O(N) — массив + СтрСоединить()ЧастиСтроки = Новый Массив;Для Каждого Элемент Из КоллекцияДанных ЦиклЧастиСтроки.Добавить(Элемент.Наименование);КонецЦикла;РезультатСтрока = СтрСоединить(ЧастиСтроки, ", ");// Для фиксированного числа подстановок — СтрШаблон() (до 10 параметров)ТекстСообщения = СтрШаблон(НСтр("ru = 'Документ %1 от %2 на сумму %3 руб.'"),НомерДокумента,Формат(ДатаДокумента, "ДЛФ=D"),Формат(Сумма, "ЧДЦ=2"));
Правило 8: Области (#Область) для организации кода
Стандарт ИТС: «Структура модуля» — обязательные стандартные области.
Стандартные области для модуля формы
#Область ОписаниеПеременных#КонецОбласти#Область ОбработчикиСобытийФормы#КонецОбласти#Область ОбработчикиСобытийЭлементовШапкиФормы#КонецОбласти#Область ОбработчикиСобытийЭлементовТаблицыФормыТовары#КонецОбласти#Область ОбработчикиКомандФормы#КонецОбласти#Область СлужебныеПроцедурыИФункции#КонецОбласти
Правила: не вкладывать глубже 2 уровней; не создавать пустые области; использовать стандартные имена из ИТС (IDE и инструменты анализа на них опираются).
Правило 9: Комментарии — объясняйте «зачем», а не «что»
Стандарт ИТС: «Описание процедур и функций» — экспортные процедуры ОБЯЗАНЫ иметь комментарий-описание.
Описание экспортной функции
// Возвращает курс валюты на указанную дату.// Если на указанную дату курс не установлен, возвращает курс на ближайшую предыдущую дату.//// Параметры:// Валюта - СправочникСсылка.Валюты - валюта, курс которой нужно получить.// ДатаКурса - Дата - дата, на которую нужен курс.// Если не указана, используется текущая дата сеанса.//// Возвращаемое значение:// Число - курс валюты. 0 если курс не найден.//Функция ПолучитьКурсВалюты(Валюта, ДатаКурса = Неопределено) Экспорт
Комментарий «зачем»
// Сумму округляем до копеек, потому что бухгалтерский учёт не допускает дробных копеек,// а при пересчёте НДС могут возникнуть дроби.СуммаНДС = Окр(СуммаБезНДС * СтавкаНДС / 100, 2);
Правило 10: Используйте НСтр() для строковых литералов
Все строки, отображаемые пользователю, оборачиваются в НСтр() — для локализуемости.
Стандарт ИТС: «Использование функции НСтр()».
ТекстПредупреждения = НСтр("ru = 'Документ не может быть проведён. Не заполнена дата.'");// С параметрами — НСтр() + СтрШаблон()ТекстСообщения = СтрШаблон(НСтр("ru = 'Остаток товара ""%1"" на складе: %2 %3'"),Номенклатура,Остаток,ЕдиницаИзмерения);
Правило 11: Одна процедура — одна ответственность
Процедура свыше 100 строк — сигнал к декомпозиции. Разделение на мелкие функции с говорящими именами делает код самодокументируемым.
Процедура ОбработкаПроведения(Отказ, РежимПроведения)ИнициализироватьДанныеДокумента();ПроверитьЗаполнениеРеквизитов(Отказ);Если Не Отказ ТогдаСформироватьДвижения(Отказ);КонецЕсли;КонецПроцедуры
Правило 12: Явная типизация параметров в комментариях
BSL динамически типизирован. Описание типов в комментарии к экспортной функции — единственный способ документировать контракт.
// Создаёт новый элемент справочника «Номенклатура» с заполнением по умолчанию.//// Параметры:// ДанныеЗаполнения - Структура - содержит поля:// * Наименование - Строка - наименование номенклатуры (обязательно).// * ВидНоменклатуры - ПеречислениеСсылка.ВидыНоменклатуры - вид (обязательно).// * ЕдиницаИзмерения - СправочникСсылка.ЕдиницыИзмерения - ед. изм. Необязательно,// по умолчанию «шт.».// * Артикул - Строка - артикул. Необязательно.//// Возвращаемое значение:// СправочникСсылка.Номенклатура - ссылка на созданный элемент.//Функция СоздатьНоменклатуру(ДанныеЗаполнения) Экспорт
Правило 13: Не используйте «Выполнить()» и «Вычислить()» без крайней необходимости
Угроза безопасности (аналог eval), невидимы для статического анализа, трудны в отладке.
// Правильно — прямой вызов через метаданныеМенеджерОбъекта = ОбщегоНазначения.МенеджерОбъектаПоСсылке(СсылкаНаОбъект);
Правило 14: Магические числа и строки — выносите в параметры
Захардкоженные значения непонятны, дублируются и не настраиваемы.
// Правильно — перечисление, значение самодокументированоЕсли Документ.Статус = Перечисления.СтатусыДокументов.Согласован Тогда// ...КонецЕсли;// Или константа для настраиваемых значенийМаксимальноеКоличествоПопыток = Константы.МаксимальноеКоличествоПопытокОтправки.Получить();
Правило 15: Явные JOIN вместо точечной нотации через ссылки
Цепочки ссылок создают неявные JOIN. При составных типах платформа делает JOIN ко всем возможным таблицам.
// Правильно — один запрос с явными JOINЗапрос = Новый Запрос;Запрос.Текст ="ВЫБРАТЬ| Товары.Номенклатура КАК Номенклатура,| Товары.Номенклатура.ВидНоменклатуры КАК ВидНоменклатуры,| Товары.Номенклатура.ЕдиницаИзмерения КАК ЕдиницаИзмерения|ИЗ| Документ.РеализацияТоваровУслуг.Товары КАК Товары|ГДЕ| Товары.Ссылка = &ДокументСсылка";
Неправильно — обращение через точку в цикле (N+1)
Для Каждого СтрокаТоваров Из Документ.Товары ЦиклВидНоменклатуры = СтрокаТоваров.Номенклатура.ВидНоменклатуры;ЕдиницаИзмерения = СтрокаТоваров.Номенклатура.ЕдиницаИзмерения;КонецЦикла;
Правило 16: Открывайте формы через ОткрытьФорму()
ПолучитьФорму() — обычное приложение, не работает в управляемом интерфейсе.
ПараметрыФормы = Новый Структура;ПараметрыФормы.Вставить("Ключ", ДокументСсылка);ОткрытьФорму("Документ.РеализацияТоваровУслуг.ФормаОбъекта",ПараметрыФормы,ЭтотОбъект,,,,Новый ОписаниеОповещения("ПослеЗакрытияФормыДокумента", ЭтотОбъект));
Правило 17: Бизнес-логика не должна жить в модуле формы
Логику записи и проверок размещайте в модуле объекта — для тестируемости и повторного использования.
// Модуль объекта документаПроцедура ПередЗаписью(Отказ)Для Каждого Строка Из Товары ЦиклСтрока.Сумма = Строка.Количество * Строка.Цена;КонецЦикла;КонецПроцедуры
Правило 18: Не проглатывайте исключения
См. error-handling, правило 1.
Правило 19: Агрегируйте серверные вызовы из формы
См. form-patterns.
Верификация через Напарника
- Проверка кода на стандарты и аналоги БСП:
ask_ai_assistant(шаблон VALIDATE_BSL изbuddy-prompting). Отдать фрагмент кода — получить нарушения стандартов и рекомендации по замене на методы БСП/платформы. - Проверка стандарта по первоисточнику:
ask_ai_assistant(шаблон SEARCH_ITS изbuddy-prompting). При расхождении навыка с ИТС — приоритет у ИТС.
depends_on: []