Без комментариев!

05.01.23

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

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

Все примеры в данной статье - вымышленные, однако созданы "по мотивам" реально встреченных комментариев.

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

Для начала изложу свои соображения по поводу того, почему вообще эта тема поднимается.

Обратимся к библии программиста 1С - документу "1С:Предприятие 8. Система стандартов и методик разработки конфигураций", раздел "Тексты модулей".

 

 

Позиция 1С по поводу комментариев в коде такова - комментарии можно оставлять, при этом есть некие условия по форматированию комментариев.

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

  1. Указание автора кода и номера задачи (авторский комментарий)
  2. Сохранение чужого (старого) кода
  3. Пояснение того, что делает код
  4. Отражение событий в мире и организации

Разберу каждый тип подробнее.

 

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С - решать вам.

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

Возможно, я слишком серьезно отношусь к недостаткам комментирования и все гораздо проще. А что вы думаете по этому поводу?

Инструментарий разработчика комментарии самодокументированный код

См. также

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

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

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

18.03.2024    1160    ZhokhovM    2    

4

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

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

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

18.03.2024    2689    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    6970    Lemmonbri    136    

36

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

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

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

19.09.2023    4350    Lemmonbri    16    

31

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

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

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

10.08.2023    9588    0    1c-izhtc    37    

21

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

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

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

11.07.2023    2214    magic1s    32    

11
Комментарии
В избранное Подписаться на ответы Сортировка: Древо развёрнутое
Свернуть все
1. sapervodichka 6697 06.01.23 00:28 Сейчас в теме
С комментариями однозначно.
Комментарий сжат номер обращения в базу поддержки, автор и дата.
Версионность кода в истории хранилища конфигурации, или git (если это есть, то старый код можно не хранить в коде, если нет, то хранить в коде).
ildary; svezr; gigapevt; kholkin; portwein; user1872456; WhiteOwl; JohnyDeath; Andreeei; Cohap; rpgshnik; kser87; Designer1C; maldinitaly; Dimel; xantif_2000; ardn; +17 Ответить
2. siamagic 06.01.23 09:06 Сейчас в теме
(1)про это и написано же - ты там нафиг не упал со свои авторством и номером обращения.
Впрочем если у вас постоянно проблемами в разработке оно как временное решение поможет.
EvgeniyOlxovskiy; +1 10 Ответить
12. sapervodichka 6697 06.01.23 13:43 Сейчас в теме
(2) В обращении в поддержку ведется большая переписка по задаче, прикладывается техническое задание и далее этот номер вставляется в код модулей и в свойства добавляемых объектов (также номер обращения/тз указывается в комментарии к версии при помещении в хранилище версии объектов ). Затем по номеру обращения в коде конфигурации можно отследить все доработки в конфигурации обычным глобальным поиском (по свойствам и модулям) и в базе поддержки вычитать все связанное описание (ну и в истории хранилища затем можно увидеть версии с номером обращения и проанализировать изменения).
Автор и дата - это стандартно все добавляют, также помогает определить быстро время и ответственному позвонить быстро узнать в чем суть.
Можешь не отвечать, я вижу ты все заранее осуждаешь. Всех благ.
ildary; Irwin; Lapitskiy; WhiteOwl; JohnyDeath; Andreeei; Altavista-; aleksandr_alyaev; GorkyGorod; dima_home; SP2000; kser87; info1i; antonpirogov; PrinzOfMunchen; mvxyz; maldinitaly; xantif_2000; +18 Ответить
15. comol 5051 06.01.23 14:02 Сейчас в теме
(12) очень надеюсь что таких "всех" уже почти не осталось... Номер задачи это конечно commit message, поиск по конфе такое дело... Лучше по гиту - быстрее раз в 50 :)
EvgeniyOlxovskiy; ccapt; nvinogradov; awk; kpotoyalo; ardn; sapervodichka; +7 Ответить
17. biimmap 1827 06.01.23 14:04 Сейчас в теме
(15) Опишите пример, как в GIT найти ВСЕ вкрапления в коде по конкретной задаче. Ведь понятно же, что в хранилище будет до 5 вставок по одной задаче, если она сложная/большая. Или ссылку на статью/видео. Поиск по GIT быстрее, но он далеко не так идеален!?!
Светлый ум; dima_home; xantif_2000; +3 Ответить
20. comol 5051 06.01.23 14:27 Сейчас в теме
(17) 1 клик по коммиту в gitlab-е... Гит я условно конечно говорю... Интерфейс тоже нужен gitlab.com туториал смотрите и внедряйте... Там столько удивительного :))))
pavlov_dv; awk; +2 Ответить
19. sapervodichka 6697 06.01.23 14:18 Сейчас в теме
(15) Git тема правильная, но она по-моему впечатлению в 5% проектов используется, ну а в десятках тысячах контор, где 1Ска у 1-10 пользователей вообще не используется, даже хранилище. По итогу most popular сейчас не git. Пока у 1С не появится как обязаловка ещё долго будут "все" вот так аккуратненько без Git'a.
21. comol 5051 06.01.23 14:28 Сейчас в теме
(19) к сожалению да... Но в мелких конторах там как то расширениями можно обойтись.... Авторский коммент выглядит уж больно жестоким
88. dima_home 238 09.01.23 13:23 Сейчас в теме
(19)

Git тема правильная


Эта тема мне больше напоминает - "как угробить свой бизнес, передав свои "яица" в "чужие руки".

"GitHub начал блокировать российских разработчиков. VPN не помогает" - https://www.cnews.ru/news/top/2019-07-29_github_blokiruet_razrabotchikov_iz_kryma
Ankare; AllexSoft; biimmap; +3 Ответить
102. biimmap 1827 09.01.23 15:52 Сейчас в теме
(88)
GitHub начал блокировать российских разработчиков. VPN не помогает


Огонь новость!
23. siamagic 06.01.23 14:59 Сейчас в теме
(12) потом сидишь через три года и офигеваешь со всяких бесполезных подписей вась петь и прочих.
А если что не так работает то по любому будешь дописывать не смотря в тикер который скорее всего уже потеряется.

И что вам мешает свою портянку вести отдельно??? если пррограммист добрался дострочек кода то очевидно они ему нужны толку от ваш рисований имен?
EvgeniyOlxovskiy; t278; ardn; +3 2 Ответить
24. sapervodichka 6697 06.01.23 15:03 Сейчас в теме
(23) всё живёт, всё меняется, если мне комментарии мешают и потеряли актуальность, то я их удаляю (например при очередном обновлении). Базы с проекта содержащие тех задания, базы с обращениями потерять - это конечно неправильно, беспорядок. ТАкие вещи надо хранить.
Ankare; zqzq; nyam-nyam; user1881120; triviumfan; PrinzOfMunchen; xantif_2000; +7 Ответить
25. siamagic 06.01.23 15:13 Сейчас в теме
(24) учитывая что может быть по 5 обращений в день на 6 программистов там через год комментариев больше чем кода будет.
тех заданий по ходу исполнения стока раз меняется что вообще фиолетово что там написано, я уж молчу что потом как правило приходится допиливать.

По сути такое засирание кода выгодно только франчам, ну сидели бы засирали в гите, или хранилище там есть для этого функционал нафига в код писать?
EvgeniyOlxovskiy; +1 Ответить
26. sapervodichka 6697 06.01.23 15:31 Сейчас в теме
(25) в любой стратегии нужно несколько принципов придерживаться:
1) Сохранять обновляемость конфигурации
2) Обеспечить читаемость кода
3) Сохранить историю изменений кода и причины изменения

- а кто будет делать ремонт в твоей квартире и по какому дизайну тебе самому решать, ведь даже самую хорошую историю могут пети и васи испортить.
nyam-nyam; xantif_2000; +2 Ответить
28. пользователь 06.01.23 18:15
Сообщение было скрыто модератором.
...
29. sapervodichka 6697 06.01.23 20:03 Сейчас в теме
(28) ты когда-нибудь ЕРП 2.4 с 50 расширениями переводил на ЕРП 2.5?
Обмен дорабатывал не типовой в типовой конфе через расширение?
Какие-то составные типы перехватывал в расширение?
Проекты на 10000 часов доработок делал?

Можешь не отвечать мастер-фломастер, ты больше по какашкам в горшках ))
SergeyTerentyev; morin; dima_home; PrinzOfMunchen; xantif_2000; biimmap; +6 Ответить
77. пользователь 09.01.23 07:15
Сообщение было скрыто модератором.
...
89. dima_home 238 09.01.23 13:34 Сейчас в теме
(25)
Такие комментарии особо помогают в двух моментах:
1. Быстрое выявление и выделение внесенных изменений в код. Особенно удобно при обновлениях.
//++
код
//--

2. Редко, но "метко" бывает так.... заказчик (например главный бухгалтер) сначала требует изменить формулу вопреки типового решения от 1С, а потом, спустя год (при аудите и проверках) начинает обвинять, что это косяки 1С и это у ИТ отдела 1С неправильно считает - и в этом случае такие записи для ИТ отдела на вес золота.
TanyTany; EvgeniyOlxovskiy; ildary; Pependos; WhiteOwl; shard; Andreeei; maaximuss; sapervodichka; +9 Ответить
96. siamagic 09.01.23 14:52 Сейчас в теме
(89) 1. Это ещё называется быдлокодерство, потому что заканчивается одинаково когда любой подписывается к месту и не месту. Хотя соглашусь удобно обновлять новичкам.

2. ты показываешь комментарий и она верит? Может служебку поискать, Бред полный.
103. пользователь 09.01.23 15:52
Сообщение было скрыто модератором.
...
122. пользователь 09.01.23 19:42
Сообщение было скрыто модератором.
...
124. пользователь 09.01.23 21:27
Сообщение было скрыто модератором.
...
61. quazare 3586 07.01.23 19:38 Сейчас в теме
(24) через полгода - год, программа "доработки" в хлам устаревают... комментарии кода не особо полезны... важен накопленный опыт
EvgeniyOlxovskiy; sapervodichka; +2 Ответить
90. dima_home 238 09.01.23 13:44 Сейчас в теме
(61)
через полгода - год, программа "доработки" в хлам устаревают... комментарии кода не особо полезны... важен накопленный опыт


Недобросовестное исполнение своих обязанностей программистов, повторно изменяющих код, не должно автоматически обвинять первоначальных программистов, написавших комментарий.
user1881120; sapervodichka; +2 Ответить
3. 1v7 235 06.01.23 09:32 Сейчас в теме
Прикрепленные файлы:
Vlan; EvgeniyOlxovskiy; zaic; user1465168; OpiVse; user1872456; user605780_L.Alexander8; AllexSoft; dima_home; SerVer1C; SP2000; Award; kser87; annamol; triviumfan; mkolpakov; PrinzOfMunchen; cheshirshik; Dimel; sapervodichka; alex_sayan; maxim_1c; ixijixi; ardn; +24 Ответить
4. a_a_burlakov 285 06.01.23 10:35 Сейчас в теме
Я иногда пользуюсь типом комментариев, похожим на "3. Пояснение того, что делает код". Я не комментирую каждую строчку, но если размер функции не превышает размер экрана, я комментариями обозначаю логические блоки функции, чтобы она лучше читалась. Например, "// Обращение к http-сервису", "// Заполнение структуры из ответа", "// Запись данных в документы".

По классическим правилам, эти комментарии можно заменить на разделение блока кода на несколько функций (которые так и будут называться: "ОбращениеКHTTPСервису" и т.д.), но, во-первых, нагромождение функций иногда мешает сосредоточиться, а во-вторых, для некоторых механизмов удобнее держать весь текст на экране (если он туда помещается).
ildary; Pependos; dima_home; Designer1C; Evg-Lylyk; ardn; +6 Ответить
30. alex_sayan 06.01.23 20:25 Сейчас в теме
(4) а чего бы этим "логическим блокам" не стать отдельными методами?
67. cybjavax 40 07.01.23 22:29 Сейчас в теме
(30) Если логические блоки не подразумевают повторного использования, то для чего их выделять в отдельные методы?
Pependos; WhiteOwl; Andreeei; dima_home; PrinzOfMunchen; +5 Ответить
75. Cmapnep 18 08.01.23 19:57 Сейчас в теме
(67) все мы так или иначе пишем для тех, кто будет дорабатывать после нас
Как знать, может твой метод еще будут использовать, если он хорош)
Идеально экспортным сделать с комментом по стандарту - вот тут уже можно все нюансы описать)
user1881120; +1 Ответить
87. cybjavax 40 09.01.23 13:06 Сейчас в теме
(75)
Прикрепленные файлы:
130. alex_sayan 10.01.23 10:25 Сейчас в теме
(67) если для тебя методы это только повторное использование кода, то поздравляю, ты живешь в стереотипах 70-х годов
nvinogradov; user1881120; +2 Ответить
137. cybjavax 40 10.01.23 14:01 Сейчас в теме
(130)
Пруфы или логика хоть какие-то будут?
138. пользователь 10.01.23 15:32
Сообщение было скрыто модератором.
...
146. alex_sayan 11.01.23 13:07 Сейчас в теме
(137) конечно будут. Читай Мартина Фаулера, Кента Бека, Стива МакКонела и многих других. В 2023 году даже как-то смешно читать, якобы методы нужны только ради повторного использования кода
149. kondratevsergey1985 11.01.23 20:14 Сейчас в теме
(67)

1. Как минимум, второстепенный код можно вынести в отдельные методы, чтобы он не мешал при чтении основного кода. Например, вынести в отдельные методы предварительные проверки, логирование и т.д.

Например, я часто делаю так:
Если Не <ТутВызовФункииПредварительнойПроверки> Тогда
Возврат;
КонецЕсли;
<ТутОсновнойКод>

2. В методах можно использовать оператор "Возврат". Возврат позволяет избавиться от многоуровневых вложенных конструкций «Если» или сложных условий в этой конструкции.

Например, та же функция предварительной проверки у меня часто выглядит так:
Если Не Условие1 Тогда
	Сообщить(…);
	Возврат Ложь;
КонецЕсли;
Если Не Условие2 Тогда
	Сообщить(…);
	Возврат Ложь;
КонецЕсли;

Возврат Истина;
Показать


3. Часто бывает такое, что читаешь портянку кода на несколько экранов, и тебе нужно внести в неё какое-то изменение, которое касается конкретной части функционала. Находишь точку, в которую можно внести изменение, но ты не уверен, что это единственная точка, возможно, выше или ниже по коду тоже затрагивается этот функционал. Приходится внимательно просматривать код целиком, убеждаться, что остальные куски никак не влияют. Если же разбивать код на методы, то это снижает связность кусков кода, программист вынужден реализовывать методы так, чтобы они решали каждый свою задачу (иначе получается монструозная конструкция из методов с большим количеством параметров). И с большей уверенностью можно внести изменения только в нужный тебе метод.

4. Если не дробить код на слишком мелкие методы и давать понятные имена методам, то упрощается навигация по коду, то есть проще добраться именно до того функционала, который тебе нужен, не отвлекаясь на анализ ненужного функционала
5. biimmap 1827 06.01.23 12:40 Сейчас в теме
По отдельности каждый из 4-х пунктов прокомментирую...

Первый про авторство:
Есть очень полезная задача, которую ни GIT ни EDT вроде бы не решает... Представим себе, что есть большая задача. Разработчик её в любом случае делает в несколько заходов (2-4). Если договориться на старте о том, что комментарий будет содержать ФИО и дату начала работы по задаче, то это становится полезным. У меня появляется возможность через поиск по всем текстам увидеть ВСЕ вставки кода по текущей задаче. Можно не писать фамилию... можно номер задачи только указывать в комментарии и дату начала работы по нему. Информация об этом особенно полезна в момент обновления конфигурации. Уже не раз сталкивался, что приходится переписывать задачу на новый релиз. В такой ситуации очень полезно видеть весь код по этой конкретной задаче вне зависимости от исполнителя даже. Другой пользы для меня нет.

Особенно стоит учесть, что когда ты увольняешься, то СФ у тебя остаётся с наработками на память, а вот GIT и EDT нет!
ildary; kholkin; Irwin; Andreeei; dima_home; sapervodichka; +6 5 Ответить
13. comol 5051 06.01.23 13:45 Сейчас в теме
(5) просто жесть.... Просто нет слов.... ФИО и дату начала работы над задачей в коде!!! Увольняешься с цф останется а git нет... 10 лет криков со всех дыр и бестолку :(
EvgeniyOlxovskiy; avbolshakov; Evg-Lylyk; +3 5 Ответить
14. biimmap 1827 06.01.23 13:49 Сейчас в теме
(13) чтоб комментарий был полезным стоит добавить ссылку на дыры...

Вот сейчас в проекте пришлось доставать один механизм для УПП, которому 10 лет! Тогда не было ни GIT ни EDT, ни дыр из которых кричали... А найти весь код по этому механизму помогло ФИО + дата.
kholkin; Irwin; user1872456; zqzq; Andreeei; nyam-nyam; +6 Ответить
16. comol 5051 06.01.23 14:03 Сейчас в теме
(14) хранилище прекрасно экспортится в гит со всей историей и авторством... Ну это так к сведению
avbolshakov; alex_sayan; sapervodichka; +3 Ответить
91. dima_home 238 09.01.23 14:14 Сейчас в теме
(16)
в гит

Мина замедленного действия.
94. пользователь 09.01.23 14:37
Сообщение было скрыто модератором.
...
151. rinso.ship 12.01.23 08:48 Сейчас в теме
(16)
Вопрос в другом. А будет ли этот GIT доступен через пару лет?
6. biimmap 1827 06.01.23 12:41 Сейчас в теме
2. Сохранение чужого кода... Сохранять код нужно только типовой, если ты его дорабатываешь. Нужно это только для упрощения обновления.

Сохранять код в разработанных командой документа/обработках и т.д. это конечно же уже лишнее.
dabu-dabu; Irwin; zqzq; Iscarimet; begemot; Evg-Lylyk; sapervodichka; +7 Ответить
7. biimmap 1827 06.01.23 12:57 Сейчас в теме
3. Пояснения в коде, что он делает.

Тут конечно вкусовщина, но я сам терпеть не могу код без комментариев! Даже игра с капитаном "Очевидность" имеет пользу.
Приведу в пример мои собственные разработки:
Кейс 1. Обработка по выгрузке и созданию регламентированных табелей из самописной базы для ведения табельного учета.

Эта волшебная обработка в длину 6000 строк кода. Если убрать комментарии - 5500. Могу точно сказать: задолбаешься читать и пытаться понять что там написано! Поэтому комментарии содержат:
-- Описание концептуальных шагов, что и зачем делается. Не всегда есть ТЗ нормальное, часто реальный алгоритм далёк от исходного ТЗ, опять же увольнение из организации с потерей доступа к материалам.
-- Особенности алгоритма, возможно критичные ошибки. Не надо забывать, что Ваши доработки кто-то будет сопровождать! Этот кейс успешно сопровождается уже 1,5 года!
-- В некоторых моментах якобы бессмысленные комментарии, которые помогают быстрее позиционироваться на нужном куске кода. Мне удобнее глазами искать нужное место по зелёным комментам, а не по основному коду! Здесь конечно вкусовщина...

Кейс 2. Конструктор выгрузки данных из ЗУП в Excel. Выгрузка в особый формат для Oracle.

Всё то же самое! Сопровождается уже 3 года!

Кейс 3. Загрузка кадровых данных из Access в УПП.

Имеется ввиду разовая миграция. Несмотря на то, что задача разовая... Но обработка тоже примерно 6000 строк кода. Т.к. исходные данные в кривом формате и сами данные не очень консистентные, приходилось выдумывать дурацкие алгоритмы, для приведения данных в порядок. Эти алгоритмы я УЖЕ не помню! Хотя задача ещё не завершена. И вот по комментам есть возможность понять, что и почему делалось. Опять же описаны особенности! Капитан очевидность тоже присутствует. Это при том, что я полностью соблюдаю стандарты разработки!

Этот кейс мой текущий проект.

Что делаю если нет комментов в коде, а нужно разобраться в чужой большой обработке!? Рисую на бумаге схему работы этого кода. Занимает это немало времени. Комментарии в коде снизили бы эти трудозатраты. Главное помнить, что пишешь это не только и не столько для себя! Тогда проще будет относиться к наличию комментариев.
ildary; m_aster; user1872456; Andreeei; nyam-nyam; dima_home; sapervodichka; +7 Ответить
31. alex_sayan 06.01.23 20:31 Сейчас в теме
(7) >>задолбаешься читать и пытаться понять что там написано!

Это проблема кода. Нужно писать читабельный, самодокументирующийся код. И проблема отпадет, а коментарии станут не нужны
34. biimmap 1827 06.01.23 23:08 Сейчас в теме
(31) Думаю стоит внимательней прочесть аргументы в моём комментарии. Код максимально читабелен и соблюдены все стандарты. Просто его много и он сложный, сложная логика работы.
EvgeniyOlxovskiy; m_aster; dima_home; sapervodichka; +4 Ответить
36. alex_sayan 07.01.23 07:22 Сейчас в теме
(34) не может быть код максимально читабельным, если в нем без комментариев не разобраться. В хорошем коде комментарии не нужны. Пытаешься написать комментарий... а он просто повторяет то, о чем уже рассказывают имена методов и переменных. И наоборот, если комментарии писать легко, значит код плохо структурирован и в коде используются невнятные имена
EvgeniyOlxovskiy; zqzq; alex_pshkv; ardn; +4 2 Ответить
40. biimmap 1827 07.01.23 12:12 Сейчас в теме
(36) Ясно. аргументы на тебя не действуют. нет смысла убеждать стену.
132. alex_sayan 10.01.23 10:35 Сейчас в теме
(40) код может быть (и должен быть!) понятным без комментариев. Обо всём могут рассказать имена методов, параметров и переменных в коде. И это прописная истина. Которую, к сожалению, знают не все 1сники
62. Alxby 1136 07.01.23 19:46 Сейчас в теме
(36)Хотелось бы увидеть обоснование, а лучше формальное доказательство, что любой код можно написать так, что добавление комментария не увеличит степень его понятности. Без этого Ваше утверждение голословно.
unknown181538; sapervodichka; +2 Ответить
131. alex_sayan 10.01.23 10:33 Сейчас в теме
(62) читай вот эту книгу:
https://www.ozon.ru/product/chistyy-kod-sozdanie-analiz-i-refaktoring-596594954/

там про комментарии разжевано на целую главу
8. biimmap 1827 06.01.23 12:59 Сейчас в теме
4. С этим пунктом полностью согласен. Никому не нужны мысли/эмоции и прочая ерунда. Комментарий должен чем-то помогать! Даже если это капитан очевидность, то помогать искать куски кода)

Спасибо за статью!
m_aster; dima_home; sapervodichka; +3 Ответить
9. noprogrammer 236 06.01.23 13:00 Сейчас в теме
Комментарий требуется только для не очень хорошего кода, что бы попытаться объяснить словами, что же этот код делает.
EvgeniyOlxovskiy; sofa07; +2 2 Ответить
10. Svb84 46 06.01.23 13:02 Сейчас в теме
Шляпа какая-то.
Сейчас в этом нет никакого смысла, два программиста, оставившие эти комментарии, уже не работают у нас, а система учета заявок и номер задачи неактуальны - мы перешли на другую систему учета заявок

Рассуждения автора основываются на лично его ситуации. У нас, например сотрудники, оставившие комментарии еще работают, система учета заявок и их номера актуальны, да и выкладывать код во внешнюю систему не имеем права. И обновление без исходного кода трудновыполнимо.
WhiteOwl; nyam-nyam; mrChOP93; user1881120; dima_home; sapervodichka; comol; +7 Ответить
11. comol 5051 06.01.23 13:41 Сейчас в теме
Стоял на дворе 2023 год... А люди в 1С по-прежнему писали авторские комменты в коде.
Хотел уже было написать "тупая статья" из разряда "спасибо кэп".... А потом прочитал комменты.
EvgeniyOlxovskiy; d_protos; eden; kuzyara; alex_sayan; ardn; +6 Ответить
95. пользователь 09.01.23 14:41
Сообщение было скрыто модератором.
...
18. OpiVse 06.01.23 14:07 Сейчас в теме
Мне, как аналитику читающему код, комментарий по п.3 удобны.
Так же вторая линия поддержки быстрее ориентируется, имея в комментариях номер задачи.
Думаю, комменты - это инструмент. «Использовать» или «не использовать» зависит от организации процесса разработки и поддержки
Stels; Andreeei; Award; ardn; sapervodichka; +5 Ответить
22. comol 5051 06.01.23 14:30 Сейчас в теме
(18) эх.... Как аналитику читающему код вам удобнее были бы ссылки на коммиты в задаче в jira... Причитайте хотя бы, как это должно быть по-человечески
27. OpiVse 06.01.23 16:05 Сейчас в теме
(22) хорошее предложение, спасибо. Где по-человечески можно почитать? Но не все ж используют jira ... "Не учите меня жить, лучше помогите материально" (с)
dima_home; +1 Ответить
32. alex_sayan 06.01.23 20:45 Сейчас в теме
Хороший код комментировать не надо. Он и так понятен. А попытка написать комментарий к хорошему коду приводит к "капитанству" - комментарий лишь повторяет то, о чем уже рассказали имена методов, переменных.
Если код нуждается в комментариях - это плохой код. Его нужно не снабжать комментариями, а переписать, снабдив говорящими именами.
Есть небольшие исключения. Например, в комментарии может быть задокументирована некая особенность. Но такие случаи довольно редкие
zqzq; alex_pshkv; 33lab; +3 Ответить
33. sapervodichka 6697 06.01.23 21:29 Сейчас в теме
(32) Можно как угодно долго предлагать НЕ комментировать, т.к. чтобы оставить комментарий нужно приложить труд (а программистам это лень делать). Многие просто не умеют описать словами, что они накодировали.
Затем надо ценить время своих коллег, у них не у всех есть время используя трассировку кода разобраться в якобы очень понятном и простом коде, поэтому комментарии ЗНАЧИТЕЛЬНО ускоряют другим понимание как отдельных блоков твоего кода так и инъекций твоего кода в типовой код поставщика.

1С приветствует комментарии к коду, к процедурам, к параметрам, к модулям.
Можно здесь почитать (автор также ссылку в статье приложил)
https://its.1c.ru/db/v8std#browse:13:-1:31:32

Огромная благодарность всем кто оставляет пояснения к своему коду.
Прикрепленные файлы:
EvgeniyOlxovskiy; ildary; kholkin; unknown181538; nyam-nyam; m_aster; AllexSoft; Award; PrinzOfMunchen; a_a_burlakov; biimmap; +11 Ответить
35. alex_sayan 07.01.23 07:14 Сейчас в теме
(33) заблуждаетесь. Время и усилия других сокращает легкочитаемый, хорошо структурированный код. А не комментарии к невнятному коду
zqzq; alex_pshkv; ardn; 33lab; +4 2 Ответить
38. sapervodichka 6697 07.01.23 08:13 Сейчас в теме
(35) Смотри ))) про необходимость комментариев к невнятному коду я не писал нигде и никак (так что это твоя личная боль).
Даже сам подумай логически, будет ли человек пишущий невнятный код тратить силы его еще и комментировать? Ему же лень написать аккуратно, а комментарий оставить лень вдвойне.

И я не заблуждаюсь, я 20 лет с 1С работаю, и тут всё совсем не идеально. Люди приходят и меняют друг друга очень часто. Тем самым создается такая российская реальность, что если ты что-то разработал и не оставил пояснений, то из этого те кто за тобой придут такую шляпу сотворят, что мама не горюй. И в этом будет именно твоя вина, т.к. тебе лень было код документировать. Да, ты сделал идеально, но не читаемо для других, ну тех кто тупее чем ты, но тоже людей, которые кушать хотят и пришли в 1С ПО разрабатывать и попался им твой идеальный код (а им твоя идеальность что в лоб что по лбу)

P.S> писать грамотный код как ты говоришь - надо однозначно. Полностью согласен, этому в ВУЗ'ах учат. А вот не комментировать(документировать) это вот совсем не нормальное поведение. Я считаю что просто это труд и человеческое время, от этого труда многие уклоняются, так как спешат за баблом.
m_aster; kholkin; user1881120; Award; PrinzOfMunchen; Designer1C; +6 Ответить
46. alex_sayan 07.01.23 16:55 Сейчас в теме
(38)
И в этом будет именно твоя вина, т.к. тебе лень было код документировать


Мне не лень. Я за правильный подход к документированию. А именно - имена переменных и методов должны документировать код


Да, ты сделал идеально, но не читаемо для других


Это и есть плохой код. Хороший код понятен всем, а не только его автору


этому в ВУЗ'ах учат


К сожалению, в ВУЗах пишут чему угодно, но не писать качественный код

А вот не комментировать(документировать) это вот совсем не нормальное поведение


В том и суть, что код и без комментариев может быть прекрасно документирован, и понятен даже школьнику
37. alex_sayan 07.01.23 07:24 Сейчас в теме
(33) стандарты 1с поверхностные в части имен в коде. Большущий пробел
39. sapervodichka 6697 07.01.23 08:18 Сейчас в теме
(37) даже такие поверхностные стандарты разработчикам просто лень соблюдать (чисто за себя отвечаю, может кто-то прям всё соблюдает в описаниях, я точно нет).

Оставлять комментарии по делу (а не мусорные комменты) - это труд, многим проще объяснить себе, что этого делать не нужно ))) Лень-то она вперёд человека родилась, заказчик в код не полезет, а бабки рядом лежат, можно их забрать и без комментариев в коде.
nyam-nyam; PrinzOfMunchen; +2 Ответить
44. alex_sayan 07.01.23 16:45 Сейчас в теме
(39) суть в том, что информация из комментариев обычно легко умещается в именах в коде

Сотрудники = Новый Массив; // Сотрудники младше 18 лет


СотрудникиМладше18Лет = Новый Массив;
EvgeniyOlxovskiy; mkolpakov; +2 Ответить
47. biimmap 1827 07.01.23 17:06 Сейчас в теме
(45) Понимаешь в чём проблема, описанный тобой пример, конечно же, отлично аргументирует твою позицию. НО!

Обмен мнениями ведётся с людьми, у которых 20 лет опыта. Скажу за себя, что в моём коде нет описанной тобой ситуации. Иногда в имени переменной или процедуры 50+ символов. В (7) комменте писал абсолютно другие примеры!
nyam-nyam; +1 Ответить
50. alex_sayan 07.01.23 17:22 Сейчас в теме
(47) 20 лет опыта вообще не аргумент. В защиту своей позиции я могу привести и авторитетные мнения:

Одной из распространенных причин для написания комментариев является низкое качество кода. Вы пишете модуль и видите, что код получился запутанным и беспорядочным. Вы знаете, что разобраться в нем невозможно. Поэтому вы говорите себе: «О, да это стоит прокомментировать!» Нет! Лучше исправьте свой код! Ясный и выразительный код с минимумом комментариев гораздо лучше громоздкого, сложного кода с большим количеством комментариев. Не тратьте время на написание комментариев, объясняющих созданную вами путаницу, — лучше потратьте его на исправление. (с) Роберт Мартин, "Чистый код"
EvgeniyOlxovskiy; zqzq; Cmapnep; alex_pshkv; mkolpakov; Bazil; vivaneev; 33lab; ardn; +9 4 Ответить
74. sapervodichka 6697 08.01.23 19:37 Сейчас в теме
(50)
Не тратьте время на написание комментариев, объясняющих созданную вами путаницу, — лучше потратьте его на исправление. (с) Роберт Мартин, "Чистый код"


Красиво льёшь мёд в уши...

Этот технический долг - это огромная проблема, которую по факту 1-ый программист не решает. Так оставь по крайней мере комментарий к своему убогому коду для 2-го программиста которому придётся за тобой это исправлять.
user1881120; dima_home; +2 Ответить
76. sapervodichka 6697 08.01.23 20:39 Сейчас в теме
(74)
к своему убогому коду
это не к тебе лично, это в целом к ситуации: Если код - убогий, то лучше, чтобы он был с комментарием чем без него. А когда дело дойдёт отдавать техдолг, тогда и стереть коммент можно (но не доходит программист в 90% случаев до техдолга)
dima_home; +1 Ответить
129. alex_sayan 10.01.23 10:15 Сейчас в теме
(74) у первого программиста руки отсохнут, если он вместо комментирования своей мешанины из кода, выправит сам код?
48. sapervodichka 6697 07.01.23 17:08 Сейчас в теме
(44) =)))

// Получим данные об операциях, которые требуется выполнить исходя из данных учетной политики и первичных документов
СоздатьОперацииКВыполнению(МенеджерВременныхТаблиц, ВидыОпераций, Период, Организация, ОтборОрганизаций);


ПолучимДанныеОбОперацияхКоторыеТребуетсяВыполнитьИсходяИзДанныхУчетнойПолитикиИПервичныхДокументов(МенеджерВременныхТаблицДляЗапроса, ВидыОперацийПоступлениеПередачиСписания, ПериодЭтотМесяц, ОрганизацияИзШапкиОбработки, ОтборОрганизацийВключенИлиНет)
EvgeniyOlxovskiy; unknown181538; dima_home; PrinzOfMunchen; biimmap; user1559729; +6 Ответить
49. alex_sayan 07.01.23 17:15 Сейчас в теме
(48) пример плохой. По набору и жирноте параметров видно, что декомпозиции там никакой. Код делает всё и сразу. Да и комментарий не сообщает ничего дельного
EvgeniyOlxovskiy; kuzyara; zqzq; vivaneev; +4 3 Ответить
140. kuzyara 1900 11.01.23 06:54 Сейчас в теме
(49) согласен. Не знаю что со мной не так, но второй вариант мне нравится больше
ПолучитьДанныеОбОперациях(МенеджерВременныхТаблиц, ВидыОперацийПоступлениеПередачиСписания, ПериодМесяц, ОрганизацияИзШапки, ОтборОрганизацийВключен)
Комментарий здесь следует вынести в описание функции(процедуры?).
// Данные об операциях, которые требуется выполнить исходя из данных учетной политики и первичных документов.
//
// Параметры: 
// ...
//
// Возвращаемое значение:
//  ...
//
Функция ПолучитьДанныеОбОперациях()
Показать
Но видимо автор его (описание) редко создает.
"Создать" - это процедура, "Получить" - это функция (не изменяет контекст). Нужно внести ясность.

заказчик в код не полезет, а бабки рядом лежат, можно их забрать и без комментариев в коде
Вроде бы говорит о других, но создается впечатление что оправдывается за себя.
EvgeniyOlxovskiy; +1 Ответить
143. AllexSoft 11.01.23 11:12 Сейчас в теме
(140) позанудствую, все таки правильно будет
Функция ДанныеОбОперациях(...)
https://its.1c.ru/db/v8std/content/647/hdoc
EvgeniyOlxovskiy; nvinogradov; +2 Ответить
148. alex_sayan 11.01.23 16:16 Сейчас в теме
(140) как уже говорил, тут проблема более глубинная. Декомпозиция выполнена плохо, метод делает много всего и сразу. От этого трудно выбрать выразительное, самодокументирующееся имя. Требуется подпорочка в виде комментария

"Выразительность для меня прежде всего означает содержательность имен. Обычно я провожу переименования по несколько раз, пока не остановлюсь на окончательном варианте. В современных средах программирования — таких, как Eclipse — переименование выполняется легко, поэтому изменения меня не беспокоят. Впрочем, выразительность не ограничивается одними лишь именами. Я также смотрю, не выполняет ли объект или метод более одной операции. Если это объект, то его, вероятно, стоит разбить на два и более объекта. Если это метод, я всегда применяю к нему прием «извлечения метода»; в итоге у меня остается основной метод, который более четко объясняет, что он делает, и не сколько подметодов, объясняющих, как он это делает" (с) Рон Джеффрис
EvgeniyOlxovskiy; user1881120; +2 Ответить
41. biimmap 1827 07.01.23 12:13 Сейчас в теме
(37) Напиши новые! Предложи Нуралиевым
45. alex_sayan 07.01.23 16:46 Сейчас в теме
(41) им пофигу на мои предложения
97. NikeeNik 74 09.01.23 14:59 Сейчас в теме
(32) Когда начинается холивар про комментирование, я обычно отвечаю шуткой: "Code is like humor. When you have to explain it, it's bad."
Которая в моём понимании в общем то и не шутка))
EvgeniyOlxovskiy; +1 Ответить
128. alex_sayan 10.01.23 10:13 Сейчас в теме
(97) понятность - превыше всего
42. ipoloskov 162 07.01.23 15:34 Сейчас в теме
Комментарии очень нужны. По их наличию я понимаю, что начал писать говнокод.
TanyTany; EvgeniyOlxovskiy; d_protos; dabu-dabu; zqzq; ovcharenko.di; awk; kuntashov; alex_sayan; 33lab; ardn; +11 1 Ответить
43. 1395969 61 07.01.23 16:40 Сейчас в теме
В чем-то согласен с автором, в чем-то нет
Пункт 4 (Отражение событий в мире и организации). Согласен, разумеется :)
Пункт 3 (Пояснение того, что делает код). Тоже частично согласен. Стараюсь давать имена переменным и функциям, "говорящими сами за себя". Избыточные комментарии не пишу
Пункт 1 (Указание автора кода и номера задачи). Не согласен с автором. Веду большое количество компаний. Какие-то из компаний перешли ко мне от других франчайзи или других программистов. Какие-то работают то со мной, то с другими программистами. Есть разные варианты ситуаций. Ведут ли другие франчайзи и другие программисты Git или что-нибудь подобное, мне не изестно. Но очень благодарен им, когда они ставят в коде комментарии, с указанием, кто, когда и что изменил или добавил. Сам тоже обязательно делаю это. Не только для других, но для себя. Когда, допустим, необходимо быстро найти, что было сделано для какой-нибудь компании, которая обращалась к тебе пару лет (месяцев, недель, дней, десятилетий и т.д.) назад.
Пункт 2 (Сохранение чужого (старого) кода). Тоже не согласен с автором. По той же причине, что и указана выше. С уважением отношусь к чужому коду. Поэтому, когда приходится его менять, то не удаляю чужой код, а заключаю его в комментарий, и добавляю запись с необходимым пояснением (см. Пункт 1)
EvgeniyOlxovskiy; PrinzOfMunchen; biimmap; sapervodichka; +4 Ответить
101. пользователь 09.01.23 15:48
Сообщение было скрыто модератором.
...
141. kuzyara 1900 11.01.23 07:23 Сейчас в теме
(43) > Пункт 1 (Указание автора кода и номера задачи)
Топикастер из инхаус разрабов и использует гит, а франчи - нет. Для первых авторский комментарий это атавизм, для вторых - необходимость.
EvgeniyOlxovskiy; user1881120; +2 Ответить
51. Dimel 07.01.23 18:05 Сейчас в теме
За годы работы у каждого программиста выработался свой стиль программирования. И хорошим стилем является комментирование:
1) Что делает функция или процедура. (Каждая процедура или функция должна делать что то одно)
2) Комментарии по вставке изменений в функционал который был разработан вендором (для облегчения обновления).
2) Комментирование костылей которые добавляются в конфигурацию (например, в редакции 3.1.15 в формах списков не работали RLS и код который устранял эту уязвимость необходим был для конкретной платформы. Те кто работают с Z платформой поймут меня по скорости исправления ошибок вендором...).
3) Комментарии при вызове API сторонних разработчиков (хорошо если это компонента о которой можно в MSDN почитать, а если это какая ни будь редкая библиотека?).
4) Комментарии при работе со сложными форматами данных. (Например выгрузки в банк клиент через текстовые файлы - что означает допустим 10-я позиция в строке? Будете искать каждый раз формат файла? А если это банк, который не выставляет в общий доступ описание форматов обмена - будете искать документацию и тратить время?)
5) Комментарии сложных алгоритмов. (Например не каждый может сходу понять как работает транзитивное замыкание Ильдаровича или сложение непересекающихся интервалов запросом).

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

Некоторые люди начитавшись Роберта Мартина с его чистым кодом или другие книги по рефакторингу, начинают применять эти патерны в своей работе бездумно. Тут важен принцип - должно быть понятно другому разработчику, который будет работать с этим кодом после вас и чтобы у него не возникло желание вас после этого убить :).

PS. Не хватает ещё возможности вставлять комментарии в запросе, чтобы они сохранялись после использования конструктора. Когда запрос в 20 строк кода, то ещё можно разобраться, но когда 2-3 тыс. строк и есть места с которыми героически кто то боролся, то без этого никак...
EvgeniyOlxovskiy; John_Davidson; ildary; dabu-dabu; nvinogradov; kholkin; greyhedgehog; nyam-nyam; m_aster; AllexSoft; SerVer1C; user1881120; sapervodichka; biimmap; +14 Ответить
52. biimmap 1827 07.01.23 18:21 Сейчас в теме
(51)
Не хватает ещё возможности вставлять комментарии в запросе


Дима за это прям 200 баллов!
83. SerVer1C 748 09.01.23 12:41 Сейчас в теме
(52) уже высказывался с аналогичным предложением на https://t.me/platform_suggestions , что и всем советую )
AllexSoft; biimmap; +2 Ответить
53. noprogrammer 236 07.01.23 18:21 Сейчас в теме
Вот лучше чем в (32) и не скажешь. Вместо того, что бы писать "человеческий" код - пишется какая нибудь простыня на 1000 строк и любезно снабжается комментарием (как будь то от этого комментария кому-то становится легче). Если код требует комментария - это плохой код (это аксиома)
EvgeniyOlxovskiy; zqzq; alex_pshkv; vivaneev; ardn; +5 Ответить
55. Dimel 07.01.23 18:47 Сейчас в теме
(53) Открываем модуль БСП общего назначения (а это я считаю одна из лучших подсистем по качеству кода) и видим:
Прикрепленные файлы:
EvgeniyOlxovskiy; m_aster; WhiteOwl; biimmap; +4 Ответить
56. noprogrammer 236 07.01.23 18:59 Сейчас в теме
(55) Данный конкретный код не требует никаких комментариев (ибо код простой и понятный).
А вот на счет того, что БСП это одна из лучший подсистем я бы конечно посgотрил (но не буду) поскольку это будет тот еще холивар.
unknown181538; +1 Ответить
133. alex_sayan 10.01.23 10:38 Сейчас в теме
(55) это как раз пример подпорок невнятного кода обильными комментариями
EvgeniyOlxovskiy; +1 Ответить
54. biimmap 1827 07.01.23 18:45 Сейчас в теме
Давайте попробую всех любителей НЕ комментировать вернуть немного в реальный мир:
1. 70% разработчиков на рынке 1С - говнокодеры! Надеюсь тут спорить особо никто не станет.
2. Примерно 2/3 от оставшихся 30% - это в целом профи, но плевать они хотели на стандарты!
3. Остаётся 10% людей которые реально способны писать вот тот самый качественный код.
4. Эти 10% обычно занимаются решением больших и сложных задач, если они перестанут их комментировать, то ни один из 90% остальных "коллег" нифига в нём не разберется, несмотря на хорошую структурированность кода и соблюдение стандартов.
5. GIT и EDT многими воспринимаются как магические заклинания и люди понятия не имеют что это такое
6. Те кто имеют понятие далеко не все его правильно используют.

Описанное выше вытекает из опыта многолетнего на проектах разного размера.

Теперь внимание вопрос:
Почему Вы по сути с пеной у рта отстаиваете что-то, если это касается всего лишь 10% всего написанного кода????

Может стоит более адекватно смотреть на реальность?! И постараться покрыть 90% реальных ситуаций, а не 10% вымышленных???

Конечно нужно остальные 90% подтягивать к 10%, но процесс это длинный и за 1 день не делается. Хорошо - если через 5 лет пропорция будет 20/80. Идеально - 30/70.

Всем любителям хорошо структурированного кода добро пожаловать в ЗУП АД! Почему этот код никто не понимает!?
EvgeniyOlxovskiy; ildary; user1465168; kholkin; Нат; unknown181538; nyam-nyam; Cmapnep; ZOMI; sapervodichka; +10 3 Ответить
57. noprogrammer 236 07.01.23 19:08 Сейчас в теме
(54)
Конечно нужно остальные 90% подтягивать к 10%, но процесс это длинный и за 1 день не делается.

Ни за 1 день ни за 100 лет - зачем если можно просто написать комментарий?
До тех пор пока будет теория о том, что можно написать какой угодно код (главное снабдить его комментом) - о хорошем коде можно забыть.
EvgeniyOlxovskiy; +1 Ответить
58. biimmap 1827 07.01.23 19:09 Сейчас в теме
(57) Если прочитать внимательно... не призываю писать какой угодно код!
nyam-nyam; sapervodichka; +2 Ответить
59. noprogrammer 236 07.01.23 19:11 Сейчас в теме
(58) Я лишь объясняю (пытаюсь объяснить) почему так ратую за отказ комментов.
60. biimmap 1827 07.01.23 19:15 Сейчас в теме
(59) так может одно другому не мешает? я вот об этом пишу много раз!
nvinogradov; sapervodichka; +2 Ответить
63. sapervodichka 6697 07.01.23 20:21 Сейчас в теме
(59)
Говнокодеры комментарии не пишут никогда.
А говнокомментарии только мешают.
Комментировать нужно уметь, на это нужно время.
Если у тебя нет времени, то не нужно этим оправдывать отсутствие комментариев.

Не писать комментарии - это не ценить время тех кто придет за тобой и порождать риски в эксплуатации системы.

P.S.
Мне как-то мастер ставил кухню, и сверлил стены. Оказалось, что трубы с водой к газовому котлу (установлен в помещении кухни) замурованы в стену и идут снизу.
В итоге мастер устанавливая крепежную ленту для нижних ящиков мне трубу с водой, идущую к котлу, просверлил. В итоге ломали стену и вызывали мастера, который котел ставил. Починили, за тем поставили кухню. + 2 дня не нужных проблем и 10 т.руб. бабок сверху это котловому мастеру-фломастеру.

Если бы мастер-фломастер по котлу оставил на стене или самом котле памятку/комментарии, то лишних телодвижений бы не было.

Многие поймут, кто например, стены сверлил в квартире и пытался понять а как электрика в стенах идет к розеткам.... комментариев то никто не оставил, а сделано всё идеально, претензий нет.

Так и не всякий код можно понять, что он делает, если это, например, расширение по интеграции с Яндекс.Сервисами без комментариев и описания )) просто вот оно есть, а как работает разбирайтесь по коду )))
ildary; evgd02; cybjavax; dima_home; user1881120; m_aster; biimmap; +7 Ответить
65. noprogrammer 236 07.01.23 21:42 Сейчас в теме
(63) Не вижу смысла спорить а тем более убеждать\доказывать что-то (спорить можно бесконечно) - я высказал свое мнение. Вы будете с упорством отстаивать свое мнение - думаю на этом и разойдемся.
EvgeniyOlxovskiy; sapervodichka; +2 Ответить
Оставьте свое сообщение