Все примеры в данной статье - вымышленные, однако созданы "по мотивам" реально встреченных комментариев.
По роду работы мне приходится читать и редактировать очень много кода. И меня огорчает огромное количество комментариев в коде, с которым я встречаюсь. Считаю, что комментарии вредны, опасны и не нужны. Комментарии мне настолько не нравятся, что в своем коде принципиально их не использую (кроме отдельных случаев, о них ниже). Обосную свое отношение.
Для начала изложу свои соображения по поводу того, почему вообще эта тема поднимается.
Обратимся к библии программиста 1С - документу "1С:Предприятие 8. Система стандартов и методик разработки конфигураций", раздел "Тексты модулей".
Позиция 1С по поводу комментариев в коде такова - комментарии можно оставлять, при этом есть некие условия по форматированию комментариев.
Попробую классифицировать типы комментариев и понять причины, что заставляют программистов оставлять комментарии в своем коде. по моим наблюдениям основные типы комментариев такие:
- Указание автора кода и номера задачи (авторский комментарий)
- Сохранение чужого (старого) кода
- Пояснение того, что делает код
- Отражение событий в мире и организации
Разберу каждый тип подробнее.
1. Указание автора кода и номера задачи
Это так называемый "авторский комментарий".
Наверное даже не надо ничего пояснять. Это традиция. Так все делают и будут делать. Когда не было технологии выгрузки исходного кода в git, комментарий был единственным способом указать себя автором изменения. У многих даже настроены шаблоны - вставка начала своего кода, вставка окончания и всякое подобное. Вот пример шаблона, который вставляет имя пользователя конфигуратора и текущие дату и время.
// Добавлено <?"""", ИмяПользователя> <?"""", ДатаВремя, """">
Такое комментирование порождает нагромождения, через которые весьма сложно пробираться:
// Вставка Иванов 11.10.2019 14:35:17
ДанныеЗаполнения.Вставить("Приоритет", ПриоритетПоПартнеру(Заказ.Партнер));
// КонецВставки Иванов 11.10.2019 15:35:17
//Смирнов 2020-01-01
ДанныеЗаполнения.Вставить("Комментарий", "Создан автоматически из обработки");
// Начало изменения Петров 25-01-2021
// Заявка 33555 - указать адрес доставки
ДанныеЗаполнения.Вставить("АдресДоставки", НовыйАдресДоставки);
// Конец изменения Петров 25-01-2021
У нас есть некая структура, которая затем используется для заполнения какого-то объекта. Это самый невинный пример, но тут мы видим на 3 строчки кода 6 строчек комментариев. Зачем мне знать сейчас, в 2023 году, что три года назад в структуру добавили ключ Приоритет, а позже добавили еще два ключа? Сейчас в этом нет никакого смысла, два программиста, оставившие эти комментарии, уже не работают у нас, а система учета заявок и номер задачи неактуальны - мы перешли на другую систему учета заявок.
Эти комментарии мешают пониманию кода. Банально приходится читать больше текста, они отвлекают от сути.
Моя основная претензия в том, что такие комментарии устаревают и по прошествии какого-то времени их наличие скорее раздражает, чем вызывает позитивные чувства (даже у любителей комментариев).
Хорошо, но авторские комментарии о "свежих" изменениях полезны? Нужны ли сейчас такие комментарии? Большой вопрос.
EDT идет уверенной поступью и все больше и больше команд переходят на разработку в EDT. Но даже если вы работаете в конфигураторе, уже давно есть инструменты, с помощью которых выгрузка исходного кода становится легкой и приятной. А если в вашей компании это не принято, вы всегда сможете выгрузить в гит самостоятельно, прямо на своем компьютере.
Git Blame - это технология, показывающая автора каждой строки кода.
Здесь я привел скриншот из модуля, открытого в Visual Studio Code. При наведении курсора на строку кода показывается, кто и когда эту строку изменил. Посмотрите, какая красота! Ничто не отвлекает от чтения и понимания кода, а если потребуется узнать, кто и когда написал какую-то строку - вот она, эта информация под рукой.
Кажется, можно перестать выделять свой код авторскими комментариями, правда?
2. Сохранение чужого (старого) кода
Эта причина иногда также вызвана соглашениями, принятыми внутри команды. Некоторые команды практикуют такой стиль написания кода - если надо что-то исправить, комментируем "старый" код, добавляем рядом свой, да еще и обрамляем все это авторским комментарием. Но часто программисты по собственной инициативе делают так же - старый код остается закомментированным, всегда можно вернуться к нему, убрав символы комментариев.
Я считаю такие комментарии мусором. Как правило, такой закомментированный код не пригождается впоследствии. Помните поговорку про "ничто не бывает таким постоянным, как временное"? Комментарии остаются балластом и мешают пониманию основного кода модулей.
К тому же, в нашей библии (стандарты разработки) есть специальное указание - в модулях недопустимо иметь закомментированные фрагменты кода.
Вдумайтесь, стандарты разработки ЗАПРЕЩАЮТ оставлять закомментированный код, а мы так делаем повсеместно!
Во всех вакансиях от программиста 1С требуют знание стандартов разработки и все соискатели рапортуют, что следуют стандартам. Однако это не мешает оставлять после себя шлейф закомментированных строк.
Встречал документ, в модуле которого 90% кода было закомментировано, причем блоки закомментированного кода были смешаны с рабочим кодом. Нужно ли объяснять, каково было дорабатывать этот модуль?
3. Пояснение того, что делает код
На первый взгляд - похвальное желание. Всем хочется, чтобы их код был понятен для понимания. Давайте оставлять поясняющие комментарии! Но и тут не все так просто.
Часто пояснение кода превращается в игру с капитаном Очевидность.
// Удалим элементы отбора Контрагент, если включена ФО ИспользоватьПартнеровКакКонтрагентов
Если ПолучитьФункциональнуюОпцию("ИспользоватьПартнеровКакКонтрагентов") Тогда
КомпоновкаДанныхСервер.УдалитьЭлементОтбораИзВсехНастроекОтчета(КомпоновщикНастроекФормы, "Контрагент");
КонецЕсли;
// Удалим элементы отбора Организация, если не включена ФО ИспользоватьНесколькоОрганизаций
Если Не ПолучитьФункциональнуюОпцию("ИспользоватьНесколькоОрганизаций") Тогда
КомпоновкаДанныхСервер.УдалитьЭлементОтбораИзВсехНастроекОтчета(КомпоновщикНастроекФормы, "Организация");
КонецЕсли;
// Удалим элементы отбора Склад, если не включена ФО ИспользоватьНесколькоСкладов
Если Не ПолучитьФункциональнуюОпцию("ИспользоватьНесколькоСкладов") Тогда
КомпоновкаДанныхСервер.УдалитьЭлементОтбораИзВсехНастроекОтчета(КомпоновщикНастроекФормы, "Склад");
КонецЕсли;
// Удалим элементы отбора ЕдиницыКоличества, если не включена ФО ИспользоватьЕдиницыИзмеренияДляОтчетов
Если Не ПолучитьФункциональнуюОпцию("ИспользоватьЕдиницыИзмеренияДляОтчетов") Тогда
КомпоновкаДанныхСервер.УдалитьПараметрИзПользовательскихНастроекОтчета(КомпоновщикНастроекФормы, "ЕдиницыКоличества");
КонецЕсли;
Обратите внимание на код выше. Каждый комментарий в нем бессмысленен, так как из кода и так все понятно - имена процедур, функций, параметров говорят сами за себя.
Приведу другой пример - на первый взгляд тут комментарий обоснован. Но почитайте код внимательней.
// отсортируем таблицу запросом по возрастанию даты для дальнейшего использования
Запрос = Новый Запрос;
Запрос.УстановитьПараметр("Приоритеты", Приоритеты);
Запрос.Текст = "ВЫБРАТЬ
| Приоритеты.ДатаЗаписи КАК ДатаЗаписи,
| Приоритеты.Номенклатура КАК Номенклатура
|ИЗ
| &Приоритеты КАК Приоритеты
|
|УПОРЯДОЧИТЬ ПО
| ДатаЗаписи УБЫВ";
В запросе одно - а в комментарии совсем другое. Что произошло? В коде изначально была допущена ошибка или же логика совпадала, но потом код доработали, а про комментарий забыли?
Лучше использовать "говорящие" названия функций и переменных, если надо - выносить участки кода в функции и процедуры с ясными осмысленными названиями. Это хорошая альтернатива комментариям, правда?
4. Отражение событий в мире и организации
У меня есть целая подборка комментариев из кода реальных баз, которые вызывают улыбку, заставляют задуматься или просто рождают чувство легкого недоумения. Я обещал не приводить реальные примеры, поэтому привожу немного отредактированные.
Пример 1
// включил механизм 01.03.2020 года по указанию Ивановой
// выключил механизм 02.03.2020 года по указанию Ивановой. Жаль...
// две недели было потрачено на разработку...
// ПроверитьЦеныПоНовомуМеханизму(Объект, Отказ);
Пример 2
// Всех принудительно заставили работать дома, новый виток короны
//
// Я не очень рад этому
УстановитьУникальныйКодПартнера(Объект);
Пример 3
// Не верю, что это поможет. Это уже третий подобный механизм в базе.
// Может быть уже скорректируем процессы, которые приводят к косякам?
ПроверитьУникальныйКодПартнера(Партнер, Отказ);
Наверное в этих комментариях есть большой глубокий смысл. Но такой код сложно назвать чистым.
Когда комментарии нужны?
Есть момент, когда комментарии все-таки нужны. Более того, они необходимы. В тех же стандартах разработки (раздел Описание процедур и функций) утверждается, что они обязательны. При создании экспортной процедуры или функции мы обязаны составить комментарий, состоящий из секций "Описание", "Параметры", "Возвращаемое значение" и "Пример". Формально это комментарий, написанный по определенным правилам. По сути - это пояснение для программиста, о том, как правильно использовать функцию. Для конфигуратора или EDT это пояснение используется для контекстной подсказки (а в EDT еще и для типизирования). Это очень полезная штука.
Забавное наблюдение: как правило люди, активно пишущие ненужные комментарии, забывают указывать описания экспортных процедур и функций.
Заключение
Использовать или не использовать комментарии в коде 1С - решать вам.
Стандарты разработки не запрещают их использовать, а соглашения внутри команды могут обязывать оставлять авторские комментарии или обрамлять комментариями старый код.
Возможно, я слишком серьезно отношусь к недостаткам комментирования и все гораздо проще. А что вы думаете по этому поводу?
