gifts2017

Комментарии. Какие и зачем?

Опубликовал Яковлевич Никита (mrXoxot) в раздел Программирование - Практика программирования

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

Все написанное ниже является моим мнением, и я буду рад критике и обсуждениям.

1. Обычный комментарий

// infostart Начало 15.11.2015
НоваяПеременная = СтараяПеременная + 1;
// infostart Окончание 15.11.2015

Узнаете? Обычный комментарий обычного программиста 1С. 

Давайте представим, что этот комментарий Вы видите через два года или его вообще писали не Вы.
Что мы из него можем понять? Кто-то что-то изменил. Разве этого достаточно?

Как можно улучшить?

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

2. Было/стало 

А = А + В;
// infostart Начало 
// Было B = A - 5:
// Стало
В = А - 4;

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

Как можно улучшить?

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

А = А + В;
В = А - 4; // infostart Было B = A - 5:

3. Идентификация новых процедур

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

 

Вроде всё в порядке, и так нам легче ориентироваться в модуле. Но есть один неприятный момент - при сравнении и объединении будут отображаться лишние изменения в разделе основной программы:

Это доставляет определенные неудобства, если измененных объектов в конфигурации много.

Как можно улучшить?

Для добавления новых процедур лучше использовать другие способы идентификации, например, префикс перед названием процедуры:

Процедура Infostart_НоваяПроцедура(Параметр1)

    Параметр1 = Параметр1 + 1

КонецПроцедуры

Напоследок еще один способ использования комментариев

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

Работает это следующим образом:

  1. Задаче присваивается уникальный идентификатор (например, ТЗ01_НДС).
  2. Во всех местах, где вносятся изменения, в комментариях указывается данный идентификатор.

Это позволяет легко и быстро найти и изменить доработанные механизмы и ничего не забыть при этом. 

Работает это следующим образом:

  1. Открываем ТЗ и находим уникальный идентификатор.
  2. Глобальным поиском находим все места, где были изменения.
  3. Дорабатываем.

Можно использовать идентификаторы и наоборот. Например, изучаете код, но не можете понять, для чего было сделано изменение. По уникальному идентификатору ищем в ТЗ необходимую информацию.


На этом все. Буду рад, если Вы поделитесь своими способами использования комментариев.

См. также

Подписаться Добавить вознаграждение

Комментарии

1. Игорь Антонов (dalgaso2010) 17.11.15 01:46
Если говорить о комментариях для описания функций, то я уже давно пришел в стилю jsDoc. Например

//**
//* Это супер функция, которая делает, что-то
//* важное.
//*
//* @param {Число} Параметр1
//* @param {СправочникСсылка.Контрагенты} Контрагент
//* @return {Массив.<СправочникСсылка.Номенклатура>}
Функция МояСуперФункция (Параметр1, Контрагент)
//TODO написать код функции
КонецФункции
...Показать Скрыть


Плюсы от такого стиля очевидны: компактность, стандартизация. Последний пункт позволяет без проблем задокументировать код и создать какой-нибудь симпатичный документ. Что касается комментариев к отдельным строкам кода, то тут лично у меня прижился уже классический вариант:

//АИВ 01.01.01 \ Комментарий / 


Или многострочный вариант

//АИВ 01.01.01 \
//Комментарий
//АИВ 01.01.01 /
2. Владислав Чинючин (vcv) 17.11.15 08:24
Многое зависит от назначения комментария. Комментарии в стиле jsDoc, помянутые в (1) полезны. Позволяют автоматически формировать документацию и понимать смысл параметров, не анализируя код.
А вот комментарии в виде
//АИВ 01.01.01 \
//Комментарий
//АИВ 01.01.01 /
или
Во всех местах, где вносятся изменения, в комментариях указывается данный идентификатор.
сильно спорны. Главная их проблема в том, что их актуальность нужно поддерживать. Вот, представьте, что для техзадания ТЗ01_НДС вы изменили строки 100-110 и отметили их комментарием. Потом, через годик, по техзаданию Т515_НДС вы в этом же модуле изменяли строки 80-120. Куда вы денете комментарий ТЗ01_НДС и какова будет его актуальность?
Для часто дописываемых проектов лучше использовать какой-нибудь git. Что бы всё было чётко: есть коммит, есть назначение коммита, есть внесенные им изменения.
o.nikolaev; +1 Ответить 2
3. С К (kraynev-navi) 17.11.15 09:04
Вот, представьте, что для техзадания ТЗ01_НДС вы изменили строки 100-110 и отметили их комментарием. Потом, через годик, по техзаданию Т515_НДС вы в этом же модуле изменяли строки 80-120. Куда вы денете комментарий ТЗ01_НДС и какова будет его актуальность?

А что мешает переделать строки 100-110 в рамках проекта по изменению 80-120?
Т.е.
//Т515_НДС (
//Комментарий 
..
//ТЗ01_НДС (
//Комментарий поясняющий изменения в связи с новой заявкой Т515_НДС 
// ) ТЗ01_НДС
...
// ) Т515_НДС 
...Показать Скрыть
4. Яковлевич Никита (mrXoxot) 17.11.15 09:16
(1) dalgaso2010,

Да, с описание параметров действительно получаются отличные комментарии. К тому же текущая версия платформы позволяет такие комментарии использовать в синтаксис-помощнике. Например как на приложенном скриншоте.
Прикрепленные файлы:
5. Яковлевич Никита (mrXoxot) 17.11.15 09:19
(2) vcv,

Главная их проблема в том, что их актуальность нужно поддерживать.

Это действительно так. Но вообще и актуальность кода лучше поддерживать.

Для часто дописываемых проектов лучше использовать какой-нибудь git. Что бы всё было чётко: есть коммит, есть назначение коммита, есть внесенные им изменения.

Ну для этого ждем EDT, кажется там уже это будет поддерживаться в полном объеме.
6. Сергей JesteR (JesteR) 17.11.15 09:50
В свои комментарии добавляю номер задачи. Задач бывает несколько и довольно долгих по времени.
Поэтому использую шаблон 1С, пример:
//{MyLogin (<?"НомерЗадачи", ВыборВарианта, 
	"Резервы", "105", 
	"Доработкая для буха", "102", 
	"Без номера", "">) <?"", ДатаВремя, "ДФ=yyyy.MM.dd">  
<?>  
//MyLogin (<?"НомерЗадачи", ВыборВарианта>) <?"", ДатаВремя, "ДФ=yyyy.MM.dd"> }
...Показать Скрыть
Y_U_S; Bassgood; АлексейП; Михаська; mrXoxot; +5 Ответить 1
7. Яковлевич Никита (mrXoxot) 17.11.15 11:01
(6) JesteR,
А вот это действительно здорово. Спасибо!
8. Владислав Чинючин (vcv) 17.11.15 11:05
(3) kraynev-navi,
А что мешает переделать строки 100-110 в рамках проекта по изменению 80-120?

Да, переделаете. Но что делать с комментарием? На сколько этот комментарий будет соответствовать результирующему коду? Особенно если его (этот комментарий и прошлое изменение) писали не вы.
Обычное же дело. Сначала изменили строки 100-110. Потом, по другому заданию, 90-110. Потом 80-100. Потом переписалось все с 50 по 150.
Куда и как девать старые комментарии?
Это действительно так. Но вообще и актуальность кода лучше поддерживать.

Но ведь гораздо проще и экономически эффективней просто писать хороший читабельный код, чем писать хороший код, к нему хорошие комментарии и поддерживать соответствие кода и комментариев.
9. Яковлевич Никита (mrXoxot) 17.11.15 12:12
(8) vcv,

Сначала изменили строки 100-110. Потом, по другому заданию, 90-110. Потом 80-100. Потом переписалось все с 50 по 150

Не исключаю, что такая ситуация может быть, но мы с этим как то не сталкивались. В случае если рядом есть изменения по другим задачам, то они просто указываются рядом.

Если потребовалось переписать все с 50 по 100, тогда это уже будет новая задача, которая исключает предыдущие.

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

Абсолютно полностью поддерживаю! Лучше писать хороший читабельный код, это факт. Но, к сожалению, не всегда это удается и тогда на выручку приходят комментарии.
10. Валерий К (klinval) 17.11.15 17:55
(0) В 3-м пункте вы написали:
Процедура Infostart_НоваяПроцедура(Параметр1)

    Параметр1 = Параметр1 + 1

КонецПроцедуры
...Показать Скрыть

А вы эту процедуру поместите в конце модуля? Просто тогда раздел основной программы будет различаться из-за #КонецОбласти....
Есть второй вариант: поместить перед разделом основной программы, но тогда будет так что, например, в область "Печать" попадёт какая-нибудь процедура "ПриИзменениЧегоЛибо".
11. Владислав Чинючин (vcv) 17.11.15 19:33
(10) klinval,
Вот кстати, не касательно пункта 3, а касательно приведенной процедуры.
Процедура Infostart_НоваяПроцедура(Параметр1)

    Параметр1 = Параметр1 + 1

КонецПроцедуры
...Показать Скрыть

Чем подобных процедур меньше, тем лучше. Неявная модификация переданного в процедуру параметра - зло.
12. Игорь Антонов (dalgaso2010) 18.11.15 01:39
(2) vcv,

Тут еще все зависит от проекта. Мне не очень нравится хранить историю комментариев, ибо потом в коде трудно ориентироваться. Для детального описания изменений есть трекер. В принципе, отследить что менялось можно истории задач. Ну а если прям нужны детали до "строчки", то тут без GIT не обойтись.
13. Олег Николаев (o.nikolaev) 18.11.15 09:02
>> Процедура Infostart_НоваяПроцедура(Параметр1)
>> Параметр1 = Параметр1 + 1
>> КонецПроцедуры

Не использую такой подход. Только хранилище и внешние СКВ (системы контроля версий).

Автор, без обид, прочитайте волшебную книжку "Совершенный код" Стива Макконнелла, там все написано по этой теме. При доработках типовых включаю хранилище и все доработки делаю через него. В комментарии к версии указываю и номер задачи и описание изменений. В том случае, если работа с клиентом заканчивается, передаю ему и хранилище и базу задач. В базе задач хранится все - кто, что, когда, зачем, файлы и т.п. (последователю понадобится и пригодится).

Для внешних обработок использую Tortosie.
Designer1C; +1 Ответить 1
14. Александр Орефков (orefkov) 18.11.15 09:28
Имхо, все эти комментарии о вносимых изменениях - от безысходности и отсутствия нормальной системы управления версиями.
Началось ещё с семёрки, да так и прижилось.
На мой взгляд, комментарии должны всегда отображать текущее состояние и пояснять только текущий функционал.
Кому нужна история - пусть копаются в летописях. Так вот в 1С - нет удобной системы их писания и копания, поэтому летописи перекочёвывают в код, превращая его в "преданья старины глубокой". На кой, извините ляд, мне знать, что три года назад тут был Вася и убрал то, что пять лет назад вписал Петя?
tormozit; yurii_host; Designer1C; Dem1urg; sbcode; ivanov660; and-blag; shootnik; CratosX; mrXoxot; o.nikolaev; FrLenok; V.Nikonov; artbear; Quasar; klinval; +16 Ответить 1
15. Артур Аюханов (artbear) 18.11.15 10:24
(0) и другие: "Авторские" комментарии - зло, как уже написали несколько человек.
Представляете, какой у вас будет код через несколько лет? немного реального кода и куча комментариев "тогда-то здесь отметился Вася по такой-то нужде" :)
Git (blame), системы код-ревью рулят.

Используйте фоновую выгрузку из 1С в Git, например, наш бесплатный открытый проект gitsync
и уже в Гите смотрите историю, кто и что, когда и почему менял.
16. Вадим Никонов (V.Nikonov) 18.11.15 10:57
По моему у комментариев есть несколько целевых задач:
1. Объяснить ход выполнения функционала, уточнить логику решения и т.п. (Это самое важное! Без этого затруднена отладка и модификация программы.)
2. Задокументировать отличия от типового решения. (Такие комментарии должны облегчать обновления типового продукта. В т.ч. содержат описания кода, который необходимо сохранить при обновлениях)
3. Протоколировать решение дополнительных прикладных задач. (Подразумевается наличие документации в виде проработанного ТЗ на доработку)

Для каждой из задач формат комментариев выглядит по разному. Вероятно, что в процессе должны писаться комментарии всех необходимых видов.
Кроме того, в ходе написания актуальных комментариев, желательно подчищать комментарии оставленные "предками". Особенно, если предыдущие доработки теряют актуальность. Например, хранить сведения, что некий коэффициент в 2010 году был 1.5, в 2012 стал 1.6, а с 2015 года равен 1.65 - вероятно не следует. Комментарий должен служить сегодняшнему и завтрашнему дню!
tormozit; Designer1C; fomix; CratosX; mrXoxot; +5 Ответить 1
17. Вадим Назаров (NazarovV) 18.11.15 12:02
Мы вот так комментируем)
//Заявка №000002911 Назаров В.Г. 18 ноября 2015 г. {{

//Заявка №000002911 Назаров В.Г. 18 ноября 2015 г. }}

Формируется автоматически в буфер из базы заявок...

Если мы комментируем чужой код или типовой есть несколько вариантов:
Если код типовой - комментируем всегда;
Если код не типовой, в нем ошибка или понимаем что логика устарела - удаляем и пишем свое.
Если код не типовой и возможно, что в будущем возможно возвращение к нему - комментим и внизу пишем свое.
Михаська; +1 Ответить
18. Владислав Чинючин (vcv) 18.11.15 12:16
(14) orefkov,
На кой, извините ляд, мне знать, что три года назад тут был Вася и убрал то, что пять лет назад вписал Петя?

В таком виде не нужно. А вот понять, зачем кто-то или ты сам вставил или закомментарил определенные строки, может быть полезно. Потому что бывают тонкости, о которых сразу не сообразишь, которые вылазят раз в месяц на определенном документе...

(15) artbear, Git и прочее рулит, но прилично написанные комментарии в коде ценны, когда ты пробегом у клиента несколько раз в году. Всему своё место. Для фикси требуется толковая система типа git, на аутсорсинге хорошо бы толковый комментарий оставить себе или другому аутсорсеру.
19. Яковлевич Никита (mrXoxot) 18.11.15 12:40
(13) o.nikolaev,

Расскажите, пожалуйста, подробнее про Tortosie - а то гугл выдает, что это тяжелый штурмовой танк.

(16) V.Nikonov,

2. Задокументировать отличия от типового решения. (Такие комментарии должны облегчать обновления типового продукта. В т.ч. содержат описания кода, который необходимо сохранить при обновлениях)

Здесь не совсем согласен. Отличия от типового решения прекрасно видны при сравнении и объединении, гораздо важнее объяснить почему здесь не устраивает типовая логика.

(18) vcv,
Git и прочее рулит, но прилично написанные комментарии в коде ценны, когда ты пробегом у клиента несколько раз в году. Всему своё место. Для фикси требуется толковая система типа git, на аутсорсинге хорошо бы толковый комментарий оставить себе или другому аутсорсеру


Да, если это изменения у обычного клиента с мелкой доработкой, то использовать Git для этой доработки, кажется, излишним.
20. Vova Vova (Vova1900) 18.11.15 12:54
Насколько я понял автора, комментарии вида "ТЗ01_НДС" предлагается использовать для связи с проектной документацией, и это полезно.
Позволяет узнать, зачем здесь этот код.

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

    Исторические комментарии вида "//AKA Vasili 31.11.2014", тоже бесполезны. Что даст информация о том, когда и кем добавлен код? Код не для этого. Для того чтобы узнать, кто и когда вносил изменения, лучше пользоваться хранилищем

    Комментарии призванные отличить типовой код от доработанного. Лучше что бы их тоже не было. Вставку на вызов собственной функции в собственном модуле можно отличить и без комментариев. А вставки целых алгоритмов в типовой код больше напоминают костыли, и им, конечно же, нужны комментарии. Если что то добавляешь, то лучше это реализовать в отдельных объектах и модулях. А если просто подправляешь типовой алгоритм по месту, то смирись с тем что это костыль, и напиши комментарий.
o.nikolaev; mrXoxot; +2 2 Ответить 1
21. Олег Николаев (o.nikolaev) 18.11.15 13:17
22. Олег Николаев (o.nikolaev) 18.11.15 13:20
(18) vcv,
Потому что бывают тонкости, о которых сразу не сообразишь, которые вылазят раз в месяц на определенном документе...

Это значит что код написано неясно. Соблазн подобного рода, за счет комментариев попытаться сгладить кривизну решения, велик, и грешат им, чоуш. Но это неправильно. Опять же, повторюсь, у Макконнела про все это написано более подробно и убедительно.
23. ООО "Студия-24бит" Компания (softcreator) 18.11.15 13:32
Я извиняюсь, а чем вам хранилище конфигурации не подходит?
Отправляем в него ту же типовую при создании хранилища, а затем пилим ее как нужно нам или заказчику. Преимущества: быстрый откат и возможность сравнения версий.
24. Валерий К (klinval) 18.11.15 14:15
(20) Vova1900,
Комментарии, поясняющие алгоритм или тонкости реализации в коде не нужны. Лучше писать понятный код. Если код нуждается в комментарии, то он также нуждается и в рефакторинге.

Я смотрю вы идеалист. Если вы пишите код на 1000+ строк и он без единого комментария понятен любому - то я вам завидую.
Исторические комментарии вида "//AKA Vasili 31.11.2014", тоже бесполезны.

У нас исторические комментарии совмещены с описанием и номером заявки. Т.е. коммент вида:
//<Определенный наш уникальный открывающий комментарий из 4 символов> Фамилия Дата КраткоеОписание (номер заявки в нашей IT системе)
Закрывающий коммент такой-же только маленько другой уникальный закрывающий тег. Т.е. мы сразу открывая модуль можем найти поиском все наши изменения. Видим кто, когда и зачем внёс. Если что-то непонятно есть номер заявки и по нему можно найти подробную информацию.
Что даст информация о том, когда и кем добавлен код? Код не для этого. Для того чтобы узнать, кто и когда вносил изменения, лучше пользоваться хранилищем

А если в модуль вносил изменения более 1 человека более 10 раз. Что вы увидите в хранилище: Иванов когда-то что-то внёс, Петров и Сидоров. А кто конкретный код внёс непонятно, надо тратить много времени на анализ хранилища. Хранилище 1с в этом плане недостаёт функционала.
А сама по себе быстрая информация кто внёс даёт возможность найти человека которого можно спросить какие-либо нюансы реализации (вместо курения кода) или можно ему перекинуть свою задачу, раз он всё-равно в курсе. Дата даёт возможность быстро понять когда этот механизм был внедрён и заработал.
VladimirL; +1 Ответить
25. Шутов Андрей (Pover) 18.11.15 17:27
К счастью на комментарии не распространяются жесткие правила. Это что то типа стиля программиста. У каждого он свой.
Полезно для посмотреть а как у "АКА Васи"
26. Fomix (fomix) 18.11.15 17:30
(23) softcreator, Хе-хе, а если Хранилище наипнется, что тогда делать будем, а?! Или место в старом закончится и придется новое делать, а?!
27. Владислав Чинючин (vcv) 18.11.15 17:37
(22) o.nikolaev,
Это значит что код написано неясно. Соблазн подобного рода, за счет комментариев попытаться сгладить кривизну решения, велик, и грешат им, чоуш. Но это неправильно.

Код, это всё же некая модель, абстракция. Полное понимание этой абстракции не даёт понимания, на сколько она соответствует требованиям и по какой причине в данном месте применена именно данная абстракция. Так что комментарии нужны. А уж где они хранятся, это вопрос второй. Хоть в описании коммита, хоть в хранилище, хоть в коде (внутри функции или перед её определением) - это уже техническая организация хранения описания абстракции.
28. Алексей Драчков (Bassgood) 19.11.15 23:25
(0) По пункту три - с версии 8.3.5, на сколько помню, для обрамления новых процедур вместо комментов можно использовать области #, выглядят они куда более симпатичнее.
29. Яковлевич Никита (mrXoxot) 19.11.15 23:38
(28) Bassgood,
Да, но проблема осталась та же. #КонецОбласти будет отображаться в сравнении и объединении. Поэтому либо не ставить такие процедуры в конец, либо не ставить такие области.
30. Алексей Драчков (Bassgood) 19.11.15 23:44
(29) mrXoxot, а что мешает ставить их в начало модуля, чтобы было сразу видно какие процедуры свои мы туда напичкали?
31. Валерий К (klinval) 20.11.15 09:21
(30) Bassgood, как вариант, но если мы обрамляем свои процедуры комментариями или #Областями то последний комментарий или #КонецОбласти попадёт в типовом сравнении к первой типовой процедуре (см. приложение).
Прикрепленные файлы:
Для написания сообщения необходимо авторизоваться
Прикрепить файл
Дополнительные параметры ответа