SyntaxMarks — Стандарты A1sCode

🐱 Кот Айван

SyntaxMarks — это GPS для кода. Глаз сразу цепляется за //✏ и //⟳. Не нужно читать каждую строку — маркеры показывают, где происходит важное.

Что это

SyntaxMarks — короткие комментарии-эмодзи в конце строк кода, которые визуально выделяют ключевые операции.

Результат = ПолучитьДанные(); //▶️ Вызов внешнего метода
ТекущаяСумма = ТекущаяСумма + Значение; //✏ Изменение переменной

Для Каждого Элемент Из Массив Цикл //⟳ Начало цикла
    // ...
КонецЦикла;

Возврат Результат; //↩ Точка выхода

Список маркеров

//✏

Изменение

Присваивание, модификация переменной или объекта

Сумма = Сумма + 1; //✏

//⟳

Цикл

Начало цикла или рекурсии

Для Каждого ... Цикл //⟳

//⚡

Тяжёлая операция

Запрос к БД, HTTP-вызов, файловая операция

Выборка = Запрос.Выполнить(); //⚡

//↩

Возврат

Точка выхода из функции

Возврат Результат; //↩

//▶️

Внешний вызов

Вызов другого модуля, API, side-effect

A1sLog.Info(Сообщение); //▶️

//⚙

Исключение

Попытка, Исключение, ВызватьИсключение

Попытка //⚙

Когда ставить

✅ Ставь маркер

На каждое присваивание в сложной функции
На начало каждого цикла
На все точки выхода (Возврат)
На вызовы внешних модулей
На тяжёлые операции (запросы, файлы)

❌ Не ставь маркер

В однострочных функциях
На очевидные операции в простом коде
Если это загромождает чтение

Правило: Маркеры нужны в сложном коде. В простых функциях из 5 строк они избыточны.

Полный пример

// Загружает данные из API и сохраняет в базу. ✦
//
// Параметры:
//  ➤ URL - Строка: Адрес API.
//  ➤ Таймаут - Число: Таймаут в секундах.
//
// Возвращает:
//  ⬅ Булево - Успех операции.
Функция ЗагрузитьИСохранить(URL, Таймаут) Экспорт
    
    ib = "Синхронизируем внешние данные с локальной БД";
    
    Попытка //⚙
        
        // Получаем данные
        Ответ = A1sWeb.Get(URL, Таймаут); //▶️ //⚡
        
        Если НЕ Ответ.Успех Тогда
            A1sLog.Warn("Ошибка загрузки: " + Ответ.Ошибка); //▶️
            Возврат Ложь; //↩
        КонецЕсли;
        
        // Парсим JSON
        Данные = A1sJ.Parse(Ответ.Тело); //▶️
        
        // Сохраняем в базу
        Записано = 0; //✏
        
        Для Каждого Элемент Из Данные Цикл //⟳
            
            НоваяЗапись = Справочники.Товары.СоздатьЭлемент(); //✏
            ЗаполнитьЗначенияСвойств(НоваяЗапись, Элемент); //▶️
            НоваяЗапись.Записать(); //⚡
            
            Записано = Записано + 1; //✏
            
        КонецЦикла;
        
        A1sLog.Info("Загружено записей: " + Записано); //▶️
        
        Возврат Истина; //↩
        
    Исключение //⚙
        
        A1sLog.Error("Критическая ошибка", ИнформацияОбОшибке()); //▶️
        Возврат Ложь; //↩
        
    КонецПопытки;
    
КонецФункции

Советы

🎯 Несколько маркеров

Можно ставить несколько маркеров на одну строку:

Ответ = HTTP.Get(URL); //▶️ //⚡

📝 С комментарием

Маркер можно дополнить текстом:

Выборка.Следующий(); //⟳ Обход результата

🔍 Поиск в IDE

Ищи //⚡ чтобы найти все тяжёлые операции

⚖️ Баланс

Не злоупотребляй. Маркеры — специи, не основное блюдо.

Шпаргалка

//✏ — Изменение
//⟳ — Цикл
//⚡ — Тяжёлая операция
//↩ — Возврат
//▶️ — Внешний вызов
//⚙ — Исключение

✏️ SyntaxMarks