Название статьи обыгрывает известное название книги Steve McConnell «Code complete». Статья отличается от множества других статей на подобную тему: текста не видно, а картинки все время двигаются. Директор нашего департамента утверждает, что сейчас среди людей преобладает клиповое мышление. Посмотрим, насколько эта статья приглянется читателям.
Первый клип посвящен объектному чтению. Это действительно очень плохой стиль программирования. Но есть хорошие новости: я научился находить в технологическом журнале все случаи объектного чтения, которые мешают работе программы. Такие запросы используют ключевые слова SELECT…Version. Запросы, которые пишут программисты, версию объекта не используют. Подробнее - infostart.ru/public/825405.
Второй клип – пожалуйста используйте форматирование. Кроме волшебных клавиш Shitf+Alt+F пригодится сочетание Shift+Tab сдвигать влево текст запросов, созданных конструктором. Если текст запроса формируется динамически, изменяется - пожалуйста, сделайте чтобы его можно было открывать конструктором для просмотра и проверок ошибок.
Синтаксические ошибки в коде программы – также как в деловой переписке свидетельствуют о незаинтересованности корреспондента. Кстати, S. McConnell глава «Форматирование и стиль», основные тезисы:
- Зрительное и интеллектуальное наслаждение, получаемое от хорошо отформатированного кода, — удовольствие, которое способны оценить лишь немногие непрограммисты
- Основная теорема форматирования гласит, что хорошее визуальное форматирование показывает логическую структуру программы
- В сложных логических выражениях размещайте каждое условие на отдельной строке
- Избегайте операторов goto
- Длина строки выражения не должна превышать 80 символов (В современной 1С – 120 )
- Используйте пробелы около скобок ( () ), чтобы сделать читаемыми логические выражения
- Что делать с частью выражения, переносимой на следующую строку
- Не выравнивайте правые части выражений присваивания (Сейчас нет единой позиции по этому вопросу. Но мне импонирует Code complete)
- Размещение каждого оператора на отдельной строке
Кроме этого, метаданные (Справочники, Документы, Регистры…) в дереве необходимо сортировать. Так гораздо аккуратнее. Реквизиты объектов можно оставить без сортировки. Исключение: нельзя сортировать подписки на события !! Потому что порядок выполнения подписок зависит от их положения в дереве метаданных, см //infostart.ru/public/554424/. Самая плохая идея - сортировать реквизиты регистров сведения (накопления).
Третий клип. Константу использовал для примера. Уверен, что Вы сможете придумать более элегантный способ избежать хардкодинга.
Чтобы вы правильно понимали, из двадцати лет работы программистом, восемнадцать лет я использовал короткие, неинформативные имена переменных. Потребовался толчок (Доброе слово и пистолет), чтобы я начал задумываться об их именах. Кстати, S. McConnell глава «Сила имен переменных», основные тезисы:
- Имя должно полно и точно описывать сущность, представляемую переменной.
- Аббревиатуры, сокращения нежелательны (ниже идет список рекомендованных сокращений).
- Короткое имя означает, что переменная будет использоваться в одной-двух строках. Многие опытные программисты вообще не используют имена вроде i.
- Чем шире область применения переменной, тем имя должно быть длиннее.
- Префикс - тип переменной в имени можно указывать или нет (По стандартам 1С ИТС – нет)
- Не нужно использовать сокращения, допускать грамматические ошибки.
- Использовать для переменных предопределенные слова, например "Записать"
Именам функции (процедуры) посвящен раздел https://its.1c.ru/db/v8std#content:647:hdoc. Если вкратце, имена не должны содержать префикс или иной намек на возвращаемый тип данных, аргументы функции (процедуры) при возможности сохранять в структуре значений, которая будет единственным аргументом, наименование функции (процедуры) должно быть настолько информативным, чтобы не было нужды в дополнительном комментарии. Кстати, S. McConnell глава «Самодокументирующийся код», основные тезисы:
- Задача документирования … во многом решается за счет хорошего стиля программирования (правильные имена переменных и функций).
- Комментарии иногда полезны, иногда - нет (перечислены случаи pro et contra. И это не намек на популярную игру, а обычная латынь. Не латунь, а латынь.)
- Не комментируйте хитрый код — перепишите его
В последнее время из имени стали убирать часто-используемое слово «Получить».
В планах – добавить клип про создание форм пользовательских интерфейсов. Пока перечислю основные тезисы:
- Рекомендуется для всех форм самостоятельно настраивать расположение реквизитов, их растягивание (по умолчанию реквизиты не должны растягиваться по горизонтали), расположение и выравнивание.
- Автоматическое расположение реквизитов допускается для форм простейших объектов (например, справочник из Наименование + Код)
- Форма для отчетов на основе СКД как правило используется из дерева метаданных Общие формы -ФормаОтчета. Это принесет дополнительные бонусы: регистрация в замерах производительности, аккуратный выбор периода отчета, стандартное редактирование настроек, обработчики реквизитов формы. В случае, если необходимо внести изменения, копируем форму из дерева метаданных общие формы в отчет, назначаем основной и изменяем.
- Для ПолныхПравПрограммистов всегда должны быть доступность и видимость всех реквизитов, если задача не подразумевает обратное. Исключение составляет реквизит номер.
- Все реквизиты шапки размещаются согласно стандартам разработки 1С Стандарт 1С: Командная панель формы документа.
- Синоним поля Дата назначается «от». Длина поля Дата 14 символов.
- Ширина поля Номер определяется, исходя из длины номера экспериментальным путём – так, чтобы все цифры помещались в поле, и при этом не было пустого пространства.
- Итоги документов размещаются согласно стандартам разработки 1С Стандарт 1С: Итоги в документах. Рекомендуется использовать стандарт в качестве образца расположения. Цветовое решение может отличаться, ввиду того, что используется другой интерфейс. За основу можно взять следующее оформление (цвет фона Web Дымчато-белый)
- В свойствах всех реквизитов шапки необходимо снимать признак Растягивать по горизонтали. При необходимости задания ширины элементов, отличной от сформированной платформой, задать значение вручную.
- Для всех документов, которые будут создаваться пользователями в количестве, большем нескольких штук, по умолчанию добавлять комментарий и автора (Ответственный). Ответственный или автор – определяется программистом самостоятельно, в зависимости от конкретной задачи. Оформление реквизитов выполняется в соответствии со стандартом Стандарт 1С: Поля Ответственный и Комментарий. В отличие от реквизитов шапки, поле комментарий может иметь признак Растягивать по горизонтали.
- Модули форм оформляются через области, используя стандартные и, при необходимости, свои.
#Область ОбработчикиСобытийФормы
#КонецОбласти
#Область ОбработчикиСобытийЭлементовФормы
#КонецОбласти
#Область ОбработчикиСобытийЭлементовФормыНаСервере
#КонецОбласти
#Область ОбработчикиКоманд
#КонецОбласти
#Область СлужебныеПроцедурыИФункции
#КонецОбласти
Отдаю себе отчет, что тема хорошего кода – высокохоливарная, поэтому конструктивные комментарии приветствуются, поощряются SM и включаются в статью. Заранее спасибо.
Порядок комментирования программного кода и изменений
1. Помещение в хранилище изменений
Любые изменения, помещаемые в хранилище, должны сопровождаться комментарием с произвольным описанием вносимых в хранилище изменений.
Пример описания вносимых изменений:
1.1. Добавлен отчёт ПРЕФИКС_Продажи
1.2. В типовой документ ПТиУ добавлен реквизит «ПРЕФИКС_Акция» и его обработка в модулях.
2. Добавление Нового функционала
Новые процедуры/функции, блоки кода должны сопровождаться комментарием в случае внесения изменений в чужой или типовой блок/модуль/объект. Для полностью своих объектов комментировать каждую процедуру не требуется.
Рекомендуется для быстрой вставки комментариев использовать текстовые Шаблоны.
2.1. Новые переменные в разделе описания переменных
//+ ПРЕФИКС <Фамилия И.О. разработчика> от <дд-мм-гггг>. <Описание задачи - опционально>
2.2. Перем НоваяПеременная1, НоваяПеременная2;
//- ПРЕФИКС <Фамилия И.О. разработчика>
2.3. Новые процедуры/функции в типовых модулях
Добавляются с префиксом «ПРЕФИКС_», кроме добавления стандартных обработчиков, описанных в п.2.8.
Новые процедуры/функции в модулях, разработанных самим разработчиком
Не нуждается в комментировании
2.4. Код внутри типовых модулей и в процедурах/функциях, разработанных другими разработчиками
//+ ПРЕФИКС <Фамилия И.О. разработчика> от <дд-мм-гггг>. <Описание кода - опционально>
код
//- ПРЕФИКС <Фамилия И.О. разработчика>
Описание кода рекомендуется использовать в случаях сложных алгоритмов и при необходимости обратить внимание других разработчиков на некие особенности данного кода/блока/процедуры/запроса.
2.5. Код в процедурах/функциях, разработанных самим разработчиком
Не нуждается в комментировании
2.6. Удаление существующей процедуры/функции – типовой или разработанной другим разработчиком
Программный код тела, начала и окончания процедуры или функции должен быть закомментирован, а перед началом этой процедуры или функции и после его/ее окончания должен быть добавлен комментарий:
//+ ПРЕФИКС Комментирование <Фамилия И.О. разработчика> от <дд-мм-гггг>. <Описание задачи - опционально>
//Процедура ИмяПроцедуры(ПараметрыПроцедуры)
// тело процедуры или функции
//КонецПроцедуры
//- ПРЕФИКС Комментирование <Фамилия И.О. разработчика>
2.7. Удаление существующей процедуры/функции, разработанной самим разработчиком
Не нуждается в комментировании
2.8. Если для решения задачи необходимо создать стандартный обработчик существующего в типовой конфигурации элемента формы или стандартный обработчик модуля объекта (ПередЗаписью, ПриЗаписи и т.п.), сначала стандартными средствами создается обработчик, а затем внутрь его помещается новый функционал по правилам п.1.4. То есть например, если в модуле объекта необходимо вставить код в процедуру ПриЗаписи(), которой нет, то результат будет следующий:
Процедура ПриЗаписи(Отказ)
//+ ПРЕФИКС <Фамилия И.О. разработчика> от <дд-мм-гггг>. <описание задачи - опционально>
код
//- ПРЕФИКС <Фамилия И.О. разработчика>
КонецПроцедуры
3. Изменение существующего типового функционала или функционала, написанного другим разработчиком.
//+ ПРЕФИКС Комментирование <Фамилия И.О. разработчика> от <дд-мм-гггг>. <Причина изменения>
// старый код
//- ПРЕФИКС Комментирование <Фамилия И.О. разработчика>
//+ ПРЕФИКС <Фамилия И.О. разработчика> от <дд-мм-гггг>. <Описание изменений - опционально>
новый код
//- ПРЕФИКС <Фамилия И.О. разработчика>
4. Любые добавления в нетиповой, исправленный, добавленный программный код, написанный другим разработчиком, комментируются в соответствие с п.2.4.
5. Создание новых объектов
При именование новых объектов конфигурации, новых реквизитов, форм, макетов, табличных частей должен использоваться префиксом «ПРЕФИКС_»
Все объекты конфигурации должны сортироваться в алфавитном порядке:
сначала типовые объекты, потом добавленные с префиксом «ПРЕФИКС_» и другими префиксами, если такие будут. При добавлении нового объекта рекомендуется сразу его передвигать по дереву в порядке сортировки.
5.1. При создании новых объектов конфигурации
- префикс «ПРЕФИКС_»
ПРЕФИКС_Справочник;
ПРЕФИКС_Документ.
5.2. При создании новых реквизитов, форм, макетов, табличных частей в типовые объекты:
-префикс «ПРЕФИКС_»
5.3. При создании новых реквизитов, форм, макетов, табличных частей в нетиповые объекты
- префикс не нужен
6. Использование перевода строки
В случае добавления кода в существующую строку типового, измененного, нового фрагмента программного кода допускается использовать перевод строки:
6.1. Вставка разделителей текста (пробел, перевод строки)
Процедура ВыполнитьОперацию(ТиповойПараметр1
//+ ПРЕФИКС <Фамилия И.О. разработчика> от <дд-мм-гггг>. <Описание задачи - опционально>
,Парам2
//- ПРЕФИКС <Фамилия И.О. разработчика>
,ТиповойПараметр3) Экспорт