Метод борьбы с большим количеством комментариев в коде

08.09.20

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

Решил поделиться нашим способом борьбы с сильно закомментированным кодом.

В нашей компании стандарт разработки запрещает разработчикам удалять «чужой» код, приходится его комментировать и дополнительно обрамлять свои изменения в комментарии. Конечно мы знаем и про GIT (даже используем в нескольких проектах) и возможности хранилища просмотреть историю изменений. Но, согласитесь, зачастую удобно, просто читая код, иметь всю информацию об изменениях (мы фиксируем номер наряда, ФИО разработчика, дату изменений и краткий смысл).  Конечно  наиболее изменяемые фрагменты становятся трудно читаемыми. Для борьбы с этим мы используем следующий подход:

  1. В модуле выделяется область «Архив кода», располагать такую область лучше в конце модуля
  2. Разработчик выделяет «замусоренный» комментариями код и используя меню "ПКМ -> Рефакторинг -> Выделить фрагмент" создает процедуру. Название процедуры лучше давать по смыслу выделенного фрагмента. Соответственно и сам фрагмент должен иметь осмысленный алгоритм, возможно это будет процедура или функция целиком.

  1. Полученную процедуру копируем в область Архив кода и к названию добавляем суффикс – дату переноса. Полезно также заключить архивную область в конструкцию #Если Сервер и НЕ Сервер. Тем самым гарантируем, что наш архив практически не будет влиять на производительность.
  2. Процедуру, которая будет исполняться, очищаем от лишних комментариев. И снабжаем своим, в котором указано, где посмотреть старый вариант. В итоге получится вот так:

  

Также этот прием полезен, когда хотим сильно изменить процедуру или функцию, а комментировать каждую строчку желания нет - отправляем текущую версию в архив, а в существующей делаем пометку, по какому наряду мы внесли изменения и где искать предыдущий вариант.

Скажите, а как вы боретесь с излишней закомментированностью кода?

Комментарии код оформление

См. также

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

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

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

18.03.2024    1162    ZhokhovM    2    

4

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

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

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

18.03.2024    2695    ZhokhovM    4    

9

Реструктуризация - бесконечная история

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

При разработке программ требуемый функционал ставят на первое место, но есть еще и архитектура программы. На горизонте 5-10 лет она становится важнее функционала, который должен работать при масштабировании и росте данных. Реструктуризация 5 терабайтной базы 1С 8.2 в формат 1С 8.3, складывает весь пазл архитектурных просчетов, которые сделали ради функционала. Как это исправить? - для разработки правильной архитектуры, нужно всего лишь сместить фокус с функционала и подумать о «вечном».

29.09.2023    1910    1CUnlimited    15    

22

Чистый код. Мой взгляд на жизнь в макаронных джунглях. Часть 2

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

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

27.09.2023    6973    Lemmonbri    136    

36

Чистый код. Мой взгляд на жизнь в макаронных джунглях. Часть 1

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

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

19.09.2023    4355    Lemmonbri    16    

31

5 подходов при доработке конфигурации 1С, чтобы в будущем не было мучительно больно её обновлять

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

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

10.08.2023    9593    0    1c-izhtc    37    

21

Задача на ошибки и неоптимальности при проведении приходной накладной

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

Задачу эту дают на собеседованиях, видимо, те франчи, которые не в состоянии оценить человека по резюме и в ходе беседы. По идее задачи, подобные этой, должны давать начинающим студентам. Но дают всем подряд. Итак: мои 5 копеек. Критика приветствуется.

11.07.2023    2217    magic1s    32    

11
Комментарии
В избранное Подписаться на ответы Сортировка: Древо развёрнутое
Свернуть все
1. user1350278 08.09.20 10:46 Сейчас в теме
Как правило, многочисленный закомментированный код, спустя месяц-другой, не нужен уже никому. Для того чтобы понять, что делал этот код и почему, придется абстрагироваться от всех более поздних наслоений (и не обязательно в модуле, где вносились изменения, они же могут быть связаны с изменениями где-то еще), а не просто прочитать несколько строчек кода.

Вы правильно заметили - для ведения истории нужна система контроля версий с нормальными комментариями коммитов, а не попытка ее промоделировать вынося "замороженный" код в модуль.

По-моему, имеет смысл сохранять прежний код только до того как новый вариант отработал месяцок в продакшн.
Все остальное, в случае разборок, вытягиваем из системы контроля версий. Хранилище 1С тут плохой помощник, согласен. Но это и так все знают и пытаются использовать что-то другое.

Немного другой подход к полезному коду, который просто именно сейчас не нужен. Его лучше хранить где-то еще, предварительно оформив в нормальный метод. Где угодно - в txt файлах, в базе разработчика и т.п. Так его и найти будет проще и рабочую базу он не "загрязняет".
2. awk 741 08.09.20 13:08 Сейчас в теме
Нарушение стандартов у вас, однако.
Закомментированный фрагмент кода, недостижимый код
Программные модули не должны иметь:
1. Закомментированных фрагментов кода,
2. Фрагментов, которые каким-либо образом связаны с процессом разработки (отладочный код, служебные отметки, например, TODO, MRG и т.п.)
3. Фрагментов связанных с конкретными разработчиками этого кода

Недопустимо оставлять подобные фрагменты в коде после завершения отладки или рефакторинга.
https://its.1c.ru/db/v8std/content/456/hdoc п.3
ИНТЕГРА; gigabyte_artur; user986734; +3 Ответить
3. stepan_s 09.09.20 06:24 Сейчас в теме
на самом деле в практике к сожалению часто бывает что задача трансформируясь во времени приходит к своему изначальному, так сказать первозданному виду :).
В этом случае очень помогает подобное версионирование, на больших задачах.
но реализовывать все же лучше средствами или хранилища, или говорят еще git может помочь :)
Но если задача мала - то оставлять коды опасно. т.к. соблазн их анализировать будет, а это потеря времени.
Итого:
Стандарты разработки (не только в 1С) говорят низя в продакшн "засирать" код.
Если нужна историй - хранилище вам в помощь.
4. tambu 65 10.09.20 03:24 Сейчас в теме
Прошу прощения, не каждый день захожу на ИС. Отвечу всем сразу. Специально упомянул в публикации и про гит и про хранилище, мы их также используем. Однако, что гит, что хранилище - это долго. Практика показала что подобные комментарии, хоть и нарушают стандарты, экономят очень много времени. У нас большие конфигурации и их много. Несколько десятков программистов, причем половина внештатников. Помимо программистов есть АБД, которые могут "глянуть" код, но не меняют его (значит и доступов в хранилище не имеют). Главное в наших комментариях - номер наряда. Далее в сервис-деске мы получим всю необходимую информацию. В том числе и о связанных изменениях (так как в нарядах зафиксированы даже изменения в других базах, если они производились в ходе работ). Причем сделать это сможет любой, кто получил доступ в код, ему не обязательно получать доступ в хранилище (иногда это десятки минут просто на подключение, плюс добавьте бюрократию) или настраивать у себя гит.
Рамзес; +1 Ответить
5. dhurricane 11.09.20 09:00 Сейчас в теме
(4)
Практика показала что подобные комментарии, хоть и нарушают стандарты, экономят очень много времени.
Опишите, пожалуйста, это поподробнее. Мне правда интересно. С одной стороны Вы указали, что "мусор" в коде усложняет чтение кода, с другой - его наличие облегчает анализ истории изменения. Как Вы достигли того баланса для себя, что описали в статье? Как оценили экономию времени с учетом трудозатрат на чтение "замусоренного" кода? Как часто приходится обращаться к истории изменений одного фрагмента? Зачем нужен быстрый доступ к истории кода, когда есть описание в сервис-деске текущей реализации?
6. tambu 65 14.09.20 09:38 Сейчас в теме
У нас достаточно большая организация и, как следствие, есть определенная бюрократия. Чтобы получить доступ к хранилищу/гит нужно будет подать заявку в сервис-деск. Отработают её не мгновенно. Да и подключение к самому хранилищу порой занимает около часа (базы большие).
Между тем, часто возникает ситуация, что для исправления ошибки или для небольших изменений привлекают разработчиков, не имеющих опыта в данной конфигурации. Им разворачивают копию базы, глушат регламенты и "вперёд". В процессе работ бывает необходимо узнать кто и зачем вносил определенные изменения. Вот тут и помогают наши комментарии. Видно автора, видно дату изменений, видно номер наряда в сервис-деске. Далее можно либо связаться с автором, либо углубленно изучить данные в наряде (там есть целый раздел, посвященный внесенным изменениям). Зачастую в комментариях сразу описан смысл изменений или другая важная информация, что позволяет лучше понять код.
Кстати, не сказать что часто, но бывают случаи, когда получив инцидент и выяснив заказчика изменений мы сообщаем эту информацию автору инцидента и больше ничего делать не приходится. Происходит это тогда, когда не все заинтересованные бизнес-подразделения получают информацию об изменениях и считают, что программа "сломалась". И самое удивительное, когда такие "расследования" показывают, что программа была изменена 3-4 года назад, а пользователи только сейчас заметили, что поведение программы их не устраивает. Тут уже человеческий фактор.
Ну и "вишенка на торте" - мы заканчиваем разработку программы индексации изменений кода. Вкратце - мы парсим код, ищем номера нарядов и фиксируем измененные объекты. Сейчас эту информацию разработчики вносят вручную, в дальнейшем будем получать автоматически. Данная база будет помощником, например архитекторам решений и тех. поддержке, в моменты обновления релизов. Зная какие наряды вошли в релиз, будет получен и список измененных объектов. А значит мы сразу увидим, если чего-то недостаёт или наоборот что-то лишнее.
7. kosmo0 108 18.09.20 15:46 Сейчас в теме
Эх, а в идеальном мире в конфигураторе есть галочка - показывать весь код или показывать только рабочий код. В первом случае видно всё всё, включая закомментированный старый неиспользуемый код. Во втором - только код который используется в текущем релизе. И даже, для уменьшения веса, фрагменты старого и/или неиспользуемого кода хранятся отдельно.


ps. А в принципе можно же использовать области. Единственно невозможно массово разворачивать/сворачивать области с заданными наименованиями. (а еще нашел в настройках такую сущность как комментарии областей - что это)
8. herfis 498 18.09.20 16:40 Сейчас в теме
Любые комментарии, пытающиеся взять на себя задачи системы контроля ревизий - это зло.
Кое-как они способны приносить пользу только пока это одноразовые "заплатки" на фоне в целом статичного года. Чем динамичнее код - тем больше вреда и хаоса они привносят.
Ну а комментарии призванные улучшить читабельность кода по определению не могут являться "лишними".
Другое дело, что "чистый" код вообще не требует комментариев. Но жизнь штука сложная, поэтому иногда комментарии нужны :)
Ну и крупные блоки иногда удобно нотировать для более быстрой навигации и быстрого понимания на уровне крупных блоков.
Если многим людям кроме разрабов требуется доступ к ревизиям, возможно стоит подумать о собственном гитовом сервере репозиториев с веб-мордой, по типу гитхаба, только в рамках организации. Я не настоящий сварщик, но про подобные решения слышал.
9. tambu 65 22.09.20 05:24 Сейчас в теме
Один из типичных кейсов использования комментариев - обновление релизов измененных типовых решений. Оставим за кадром использование расширений (я пока не видел удобных инструментов для расширений, которые сравнимы с показом дважды измененных объектов).
Так вот при обновлении релизов крайне полезно сразу видеть, что код менялся нами, а не разработчиками 1С. Даже не представляю как это быстро проверить в любой системе контроля версий. А комментарии очень выручают, равно как и использование префиксов для собственных реквизитов и объектов.
Оставьте свое сообщение