Как избавиться от большого количества комментариев в коде с использованием EDT + Git

15.11.22

Разработка - Рефакторинг и качество кода

Публикация освещает вопрос улучшения качества и читабельности кода путем отказа от излишних комментариев. Рассматривается пример из опыта работы команды разработки на EDT + Git. Команда работает в EDT меньше года. Конфигурация сильно доработана и не обновляется типовыми релизами.

Многие команды разработчиков в процессе выполнения доработок обрамляют код своими (фамильными) комментариями, а также не забывают оставить предыдущую версию кода в виде комментария. Эти комментарии помогают в любой момент времени понять: кто, когда, по какой задаче и какие изменения внес.

// {begin 03.06.2022 Жу... №10208 }
//	    Параметры_С.Вставить("НадписьИнфо", строка_ВыгодаПоКарте);
	    Параметры_С.Вставить("НадписьИнфо", Элементы.ДекорацияИнфо03.Заголовок);
// {end 03.06.2022 Жу... №10208 }

Статья посвящена обратному процессу, то есть, очистке этих комментариев из конфигурации. Интерес к этой статье может появиться у команд, которые перешли, находятся в процессе перехода или планируют переход на EDT + git.

Суть проблемы

Ни для кого не секрет, что в процессе развития бизнеса у программистов появляется все больше и больше задач на доработку. Решение этих задач чаще всего (не всегда) связано с внесением программистами нового кода. Со временем, в результате разработки нового функционала, в системе появляется все больше комментариев. Через несколько лет (или раньше, зависит от размера команды и прыткости каждого ее члена) разработчики начинают терять приличное время на чтение и понимание кода, что отражается на их производительности. Код становится плохо читаем, а скрыть эти комментарии не представляется возможным (в пределах среды разработки).

Польза же от самих комментариев снижается со временем. Есть несколько причин:

Комменты поверх комментов. Разработчики вносят все больше и больше правок, иногда поверх уже кем то доработанного ранее кода. И тут появляется сложность при чтении кода, т.к. надо еще понять, а какой комментарий к чему относится, какой свежее и правильнее. Особенно это касается часто изменяемых участков кода. 

Устаревание комментария. Со временем бизнес логика меняется, и изначальный комментарий становится не актуальным для прикладной задачи. При этом разработчику при выполнении доработки приходится читать длинные поясняющие комментарии или закомментированный другими разработчиками код. 

Качество самих комментариев. Иногда разработчик оставляет неоднозначные комментарии, над которыми, порой, думаешь дольше, чем над самим кодом.  

Большое количество комментариев загромождает код, и сильно отвлекает разработчика от основной задачи - понять, что же этот код делает. Мое самое любимое - это закомментированный запрос в 100500 строк, и следом исправленный вариант запроса. Пока пролистаешь, забудешь о чем шла речь. Еще очень приятно, когда посреди запроса прячутся комменты..

Отрицание

Долгое время наша команда не замечала подобных проблем, пока в один прекрасный день разработчик (привет Геец) не стал жаловаться на сложность понимания кода из за огромного количества комментов. Поинтересовавшись у всей команды, выяснилось, что все испытывают подобную трудность. Терпят и молчат, молчат и терпят. Похоже, нам надо больше общаться..

&НаКлиенте
Процедура ДобавитьВКорзинуФрагмент(ВыбранноеЗначение_ТЗ)
	
	//НовыеСтроки = ПараметрыДанных.НовыеСтроки;
	//ПараметрыТовара = ПараметрыДанных.ПараметрыТовара;
	// Начало изменений БИТ Пят... И.Н.
	//	Если Объект.Товары.Количество() = 0 И (Не СуммаСдачи = 0) Тогда
	//		СуммаСдачи = 0;	
	//	КонецЕсли;	
	// Окончание изменений БИТ Пят... И.Н.
	
	//ВИТТА_ЛАА_2017-12-05 {
	Если ВИТТА_ОптимизированноеПробитие Тогда
		//КопияОбъекта = Объект;
		//ВИТТА_ДобавитьВКорзинуНаСервере(ВыбранноеЗначение_ТЗ, КопияОбъекта, ПараметрыУказанияСерий, ИдентификаторЧековойСмены, ТекущийПродавец);
		//КопироватьДанныеФормы(КопияОбъекта, Объект);
		ВИТТА_ДобавитьВКорзинуНаКлиенте(ВыбранноеЗначение_ТЗ);
		//Если ТекущаяСтрока <> Неопределено Тогда
		//	Элементы.РеквизитТаблица.ТекущаяСтрока = ТекущаяСтрока.ПолучитьИдентификатор();
		//	СтрокаДисплеяПокупателя = Строка(ТекущаяСтрока.Номенклатура);
		//КонецЕсли;	
	Иначе
		ДобавитьВКорзинуНаСервере(ВыбранноеЗначение_ТЗ);//ПараметрыТовара, НовыеСтроки);
	КонецЕсли;
	//ВИТТА_ЛАА_2017-12-05 }	
	
	//	Если Не ИспользоватьНоменклатуруПродаваемуюСовместно Тогда
	//		ПодборТоваровКлиентСервер.УстановитьТекстИнформационнойНадписи(ЭтаФорма);
	//	КонецЕсли;
	
	СкидкиНаценкиКлиент.СброситьФлагСкидкиРассчитаны(ЭтаФорма);
	//ВИТТА_ЛАА_2017-12-05 {
	Если НЕ ВИТТА_ОптимизированноеПробитие Тогда	
		БИТ_ЧекККМКлиент.ПересчитатьДокументНаКлиенте(ЭтаФорма, Объект, Истина);	
		Модифицированность = Истина;
	КонецЕсли;
	//ВИТТА_ЛАА_2017-12-05 }
	
	// Если добавление товара в корзину производилось при заполненной строке поиска,
	// то вернуть фокус ввода на строку поиска.
	//ИмяТекущегоЭлементаСтрокиПоиска = ПодборТоваровКлиент.ИмяТекущегоЭлементаСтрокиПоиска(ЭтаФорма);
	//Если ЗначениеЗаполнено(ЭтаФорма[ИмяТекущегоЭлементаСтрокиПоиска]) Тогда
	//	ПодборТоваровКлиент.УстановитьТекущийЭлементСтрокаПоиска(ЭтаФорма);
	//КонецЕсли;
	
КонецПроцедуры

Согласитесь, подобный код читать нелегко. Нужно в коде из 40 строк найти 10 полезных.

Сделал простой опросник на Google Forms для команды разработчиков. Вот, какие результаты мы получили:

 

 

Приняли решение обсудить этот вопрос на ретроспективе.

Гнев

На ретроспективе мнения разделились. Некоторым разработчикам эти комментарии казались полезными, кто то без них не может жить (привычка). Большинство посчитало, что основная часть комментариев не несет никакой ценности, и может быть просто уничтожено. Но возник вопрос, а как быть с полезными комментариями?  

Нам не удалось принять решение и придти к консенсусу по поводу комментариев. Однако, немного поработав совместно на доске Miro, нам удалось классифицировать комментарии, которыми пользуется команда, накидать предложений (иногда даже безумных) для последующего мозгового штурма, и наметить дальнейший план действий.

Вот что из этого получилось:

 

Решением по итогам ретроспективы стало

1. Проведение мозгового штурма (к следующей ретроспективе договорились, что каждый разработчик оставит свой стикер с комментариями и мыслями под каждой идеей)

2. К следующей ретроспективе изучаем стандарты в части комментариев, смотрим практику других команд. Назначены ответственные.

Торг

К следующей ретроспективе мы подошли более подготовлено. Изучили стандарты, пообщались с другими командами (в том числе не 1с разработчики), разработчики высказались по идеям на доске Miro:

 

На картинке не все видно, но суть отражает.

Команды, разрабатывающие приложения не на 1с, так или иначе используют систему контроля версий, и никогда не пишут комментарии по каждой измененной строке кода. Какие-то команды используют удаленные Git репозитории, кто то разворачивает его в компании локально. Для просмотра изменений используют функционал Git (GitLab, GitHub, Bitbucket), некоторые команды считают удобным использование приложений (SMARTGIT и прочие).

В результате длительного обсуждения, прений и разногласий, команда пришла к выводу, что для просмотра истории изменения кода функционала Git + EDT будет достаточно. Главное вносить корректные коммиты, целиком отражающие суть внесенных изменений.

Решения, принятые на ретро:

1) Сносим все (не несущие пользы) комментарии в части кода, который сейчас дорабатывается и будет тестироваться.

2) Добавляем комменты для кода, который будем менять / удалять в будущем (например, после проверки гипотез).

3) Добавляем комменты для кода, который можно интерпретировать неоднозначно. Комментарии,  в этом случае, поясняют программисту, почему именно так и не иначе.

4) Оставляем практику описания процедур и функций. 

Депрессия

После завершения ретроспективы все разошлись по рабочим местам, и приступили к написанию кода "по-новому", соблюдая договоренности, достигнутые на ретро. Однако, некоторым разработчикам было тяжело изменить манеру написания своего кода, старые комментарии казались очень ценными, их уничтожение казалось невосполнимой утратой. Новые комментарии очень сильно напрашивались. Причина тому - не все до конца понимали, как работают механизмы  чтения истории кода в EDT, а разбираться лень и некогда. 

Решение пришло достаточно быстро. При слиянии веток видно, что разработчик добавил лишний комментарий. С такими комментарием пришлось поработать, показать разработчику функционал по просмотру истории кода в EDT, и проконтролировать дальнейшие его доработки на наличие коментов.

Принятие

Постепенно команда начала понимать, что вся история сохраняется, ее просмотр не доставляет неудобств и не занимает много времени. При этом код становится чище, и на его чтение тратится меньше времени.

Для приличия, на примере редактирования части модуля посмотрим функционал EDT для просмотра истории изменения кода:                           

Если ЗначениеЗаполнено(Источник.ВИТТА_Основание) Тогда //по заказу
	СтруктураДжСон.Вставить("order_id",Источник.ВИТТА_Основание.НомерПоДаннымКлиента);          //Номер заказа
	//begin 25.12.2020 ВИТТА Ант... № 835
	//СтруктураДжСон.Вставить("add_txn_id",?(Источник.ВИТТА_Основание.ВИТТА_ИсточникЗаказа = Перечисления.ВИТТА_ИсточникЗаказа.Телефон,Источник.Номер,""));//Идентификатор чека
	//end 25.12.2020 ВИТТА Ант... № 835
	СтруктураДжСон.Вставить("order_total",Источник.ВИТТА_Основание.СуммаДокумента);				//Сумма заказа
Иначе
	СтруктураДжСон.Вставить("order_total",Источник.СуммаДокумента);
	//begin 25.12.2020 ВИТТА Ант... № 835
	СтруктураДжСон.Вставить("add_txn_id", Источник.Номер);//Идентификатор чека
	СтруктураДжСон.Вставить("client_id", СокрЛП(Источник.Склад.Код));
	
//end 25.12.2020 ВИТТА Ант... № 835
КонецЕсли;

Убираем комментарии из кода


Если ЗначениеЗаполнено(Источник.ВИТТА_Основание) Тогда
     СтруктураДжСон.Вставить("order_id",Источник.ВИТТА_Основание.НомерПоДаннымКлиента);          
	 СтруктураДжСон.Вставить("order_total",Источник.ВИТТА_Основание.СуммаДокумента);				
Иначе
	 СтруктураДжСон.Вставить("order_total",Источник.СуммаДокумента);
	 СтруктураДжСон.Вставить("add_txn_id", Источник.Номер);										
	 СтруктураДжСон.Вставить("client_id", СокрЛП(Источник.Склад.Код));
КонецЕсли;

В коммите GIT указываем, по какой задаче работали, и что сделано (в примере просто укажу номер задачи). Сливаем ветку в основную. Далее разработчики затягивают эти изменения в свои ветки.

Для просмотра истории кода в EDT команда использует несколько возможностей:

 

1 способ. Непосредственно в дереве объектов есть возможность открыть историю изменения объекта:

 

 

Открывается вся история изменений этого объекта. В истории видим, кто, когда и зачем внес изменения:

 

 

С помощью прокрутки увидим сами изменения:

 

 

2 способ. В контексте самого модуля можно сразу видеть какие строки были изменены. Для этого надо щелкнуть правой кнопкой мыши на левом поле редактора и выбрать пункт "Показать информацию о редакции". В этом случае, EDT начнет выделять цветом измененные строки прямо в редакторе:

 

 

На полях появятся подкрашенные номера строк, что свидетельствует о том, что можно посмотреть историю изменений.

 

 

 

При наведении мышкой на подкрашенную строчку, можно перейти к истории.

 

 

Можно открыть информацию, и прокрутить к нужной строке. Снова наводим мышь на подкрашенное поле, EDT покажет, что было изменено.

 

 

Замечу, что все изменения так же можно найти в любой системе контроля версий. Как бы, для этого они и предназначены.

Написание этой статьи спровоцировано отсутствием подобной информации (по крайней мере, мы не нашли за короткое время). Нам бы она помогла в свое время. Надеюсь, она будет полезна тем командам, которые столкнутся с подобной проблемой.

Вот так, по простому о сложном или сложно о простом, кому как зайдет.

Основной вопрос, который у меня возникает: как измерить эффект от этих изменений, дать оценку. Насколько улучшилась читаемость кода, на сколько ускорилась разработка? Пока планирую собирать обратную связь от программистов. А что думает сообщество?

Комментарии EDT git

См. также

Автотесты для типовых конфигураций ERP Управление предприятием 2 и Комплексная автоматизация 2 (для vanessa automation)

Тестирование QA DevOps и автоматизация разработки Платформа 1С v8.3 1С:ERP Управление предприятием 2 1С:Комплексная автоматизация 2.х Россия Бухгалтерский учет Налоговый учет Платные (руб)

Готовые тестовые сценарии, предназначенные для регресс-тестирования функционала конфигурации после обновления типовым релизом. Сценарии проверяют интерактивное заполнение форм документов, справочников и результат проведения документов. Сценарии возможно использовать как для vanessa-automation, так и для СППР. Поддерживаемые версии конфигураций ERP2 и КА2: 2.5.15.111.

2220 руб.

04.07.2022    6724    26    0    

22

Системы контроля версий для 1С-разработчиков.

1С-программирование DevOps и автоматизация разработки Групповая разработка (Git, хранилище) DevOps для 1С Платформа 1С v8.3 Платные (руб)

Основы командной разработки на 1С. Использование систем контроля версий при разработке на платформе 1С:Предприятие 8

4900 руб.

29.06.2022    9143    78    4    

110

Автотесты для типовых конфигураций Бухгалтерия предприятия КОРП 3.0 и Бухгалтерия предприятия 3.0 (vanessa automation)

Тестирование QA DevOps и автоматизация разработки Платформа 1С v8.3 1С:Бухгалтерия 3.0 Россия Бухгалтерский учет Налоговый учет Платные (руб)

Готовые тестовые сценарии, предназначенные для регресс-тестирования функционала конфигурации после обновления типовым релизом. Сценарии проверяют интерактивное заполнение форм документов, справочников и результат проведения документов. Сценарий – feature-файл, разработанный с помощью vanessa-automation. Запуск сценария выполняется интерактивно с помощью vanessa-automation или с помощью vanessa-runner в CI-системах. Доступно тестирование тонкого клиента. Поддерживаемые версии конфигураций 1С:Бухгалтерия предприятие 3.0 и версии КОРП: 3.0.144.49.

1728 руб.

20.01.2022    6590    10    0    

9

Автоматическое подтверждение легальности обновления базы или как обновить 100 типовых баз 1С за 5 часов

DevOps и автоматизация разработки Обновление 1С Платформа 1С v8.3 Конфигурации 1cv8 1С:Бухгалтерия 3.0 1С:Зарплата и Управление Персоналом 3.x Абонемент ($m)

Расширение для конфигураций 1С для автоматического подтверждения легальности обновления и выполнения обработчиков обновления при пакетном автоматическом обновлении большого числа баз 1С. А также сам модуль обработки по автоматическому обновлению баз.

2 стартмани

08.05.2019    24213    54    VPanin56    26    

26

Когда понадобился новый оператор

Рефакторинг и качество кода Платформа 1С v8.3 Конфигурации 1cv8 Бесплатно (free)

Когда понадобился новый оператор, но его нет в синтакс-помощнике, что делать?

18.03.2024    1152    ZhokhovM    2    

4

Когда разработчик платформы не добавил проверку препроцессоров

Рефакторинг и качество кода Платформа 1С v8.3 Конфигурации 1cv8 Бесплатно (free)

Когда разработчик платформы решил пойти на кухню за кофе, а проверку препроцессоров не добавил, и вот тут-то и началось: "Что, опять все сломалось? Ну и кофе же я забыл сделать!".😅

18.03.2024    2677    ZhokhovM    4    

8

1С, СППР и Архитектура как код

DevOps и автоматизация разработки Бесплатно (free)

Можно ли идеи подхода «Архитектура как код» положить на 1С или иную платформу, чтобы не изобретать ещё какой-то язык и сразу получить множество готовых библиотек функций и инструмент достижения главной цели подхода AaC.

01.02.2024    2463    roman72    9    

7

TCP прокси-сервер хранилища конфигурации 1С

DevOps и автоматизация разработки Групповая разработка (Git, хранилище) OneScript Платформа 1С v8.3 Бесплатно (free)

Продолжение истории с прокси хранилища, но уже не на HTTP, а на TCP и без падений по памяти веб-сервера. Проверяем комментарии хранилища, вызываем веб-хуки, старты пайплайнов, gitsync по событию помещения версии в хранилище. И все это полностью на знакомом и понятном OneScript.

17.01.2024    2772    kamisov    17    

57
Комментарии
В избранное Подписаться на ответы Сортировка: Древо развёрнутое
Свернуть все
1. sapervodichka 6697 15.11.22 09:16 Сейчас в теме
Думаю надо еще в сторону обновляемости копать: изменение форм переделывать на динамический вывод элементов, события на перехват подключаемых команд, часть автономных доработок переносить в расширения.
Рамзес; shastin87; +2 Ответить
2. shastin87 9 15.11.22 11:34 Сейчас в теме
(1) Но это, как говорит Леонид Каневский, уже совсем другая история..
3. dhurricane 15.11.22 15:42 Сейчас в теме
Осталось дело за малым - перейти на EDT. :-) Ну что касается темы статьи, то мне видится идеальным подходом на данный момент с одной стороны отсутствие каких-либо служебных комментариев в нетиповых объектах конфигурации и обрамляющие (без сохранения исходного кода) служебные комментарии в типовых модулях.
sapervodichka; t278; +2 Ответить
4. shastin87 9 15.11.22 16:06 Сейчас в теме
(3) Функционал Git можно использовать и без EDT, оставаясь в конфигураторе. Для этого в конфигураторе есть возможность выгружать конфу в файлы, и загружать из файлов. А вот уже система контроля версий поможет сохранить и показать историю изменения кода.
sapervodichka; +1 Ответить
5. dhurricane 15.11.22 16:44 Сейчас в теме
(4) Мы его используем, но это далеко не так удобно, как blame прямо в редакторе модуля.
sapervodichka; +1 Ответить
Оставьте свое сообщение