Вход | Регистрация
 

Какие у вас есть правила по комментированию кода в конфигурации?

Какие у вас есть правила по комментированию кода в конфигурации?
Я
   toypaul
 
02.12.20 - 15:38
Сейчас у меня есть в основном только отрицательный опыт при работе с конфигурациями, над которыми глумились разные фирмы и разработчики.

Представляет это из себя жуткое зрелище - сплошные вложенные камменты и среди них код с ускользающим смыслом.

Каждый раз когда вижу такую конфу какая-то моральная травма.

Ведь должно же быть как-то по другому - в идеальном мире :)

Какой у вас есть положительный опыт когда нужно куче разработчиков вносить изменения в конфы которые поддерживаются годами?

Сколько должен жить старый код и должен ли он вообще жить?
   toypaul
 
1 - 02.12.20 - 15:44
И расскажите не стесняйтесь если у вас такой же подход в разработке используется :)
Почему так вышло? Может и в этом есть какой-то смысл :)
   Garykom
 
2 - 02.12.20 - 15:46
git самое лучшее, там и история и комменты
   fisher
 
3 - 02.12.20 - 15:48
А куда деваться, если нету VCS?
А многие такое даже при наличии хранилища фигачат.
При наличии VCS (если недовозможности хранилища напрягают, то можно зеркалировать его в git или сразу в git) - это все нафиг не нужно. Код должен быть предельно чистым. Все остальное - задача VCS
   fisher
 
4 - 02.12.20 - 15:54
Проблема обычно с "беспризорными" продуктами, которые время от времени сопровождаются разными франчами. Там уж особо ничего не попишешь. Приходится в коде "версионировать". Но там обычно и изменения "заплаточные", поэтому до абсурда редко дотягивают.
   mikecool
 
5 - 02.12.20 - 15:59
начал читать "Чистый код" и тоже понял, насколько текущая конфига завалена комментами
предложил почистить, а в ответ "не надо, а то потом не найдем кто и что изменял, для быстрого разбора полетов надо оставить"
гит не пользуем, только хранилище
и дежит тонна лапши из комментов мертвым грузом...
   toypaul
 
6 - 02.12.20 - 16:00
каменты к комиту это как бы одно. а каменты к смыслу кода - это другое. иногда между собой вроде и связанное но не обязательно.

я вот где-то регламент читал такой - если комментируем чужой код, то оставляем максимум 2 уровня вложенности - свой и комментируемы. все остальное удаляем к чертям.
   toypaul
 
7 - 02.12.20 - 16:01
предложил почистить, а в ответ "не надо, а то потом не найдем кто и что изменял, для быстрого разбора полетов надо оставить" - это бред сивой кобылы
   toypaul
 
8 - 02.12.20 - 16:01
+ (7) имею ввиду отговорка эта
   Джинн
 
9 - 02.12.20 - 16:09
(6) Добавленный код отмечаю начальным и конечным комментарием со значком "+"
Удаленный код отмечаю начальным и конечным комментарием со значком "-" и комментирую его
Измененный код отмечаю начальным и конечным комментарием со значком "+/-", комментирую старый кусок и добавляю свой. Иногда сложно так сделать, т.к. куски "неразрывные". Тогда меняю и в комментарии пишу что поменял.

Естественно во всех случая в комментарии пишу для чего изменено.
   Garykom
 
10 - 02.12.20 - 16:10
Было бы прикольно если 1С встроила гит в платформу и данные хранились в самой конфе/базе, по желанию
   mikecool
 
11 - 02.12.20 - 16:10
(8) согласен, надо подумать насчет гит и выгружать модули в него
я пока с ним не особо знаком, но думаю разбор полетов в нем должно мочь быстро устраивать
   toypaul
 
12 - 02.12.20 - 16:12
(9) а если уровней каментов 10? да даже не 10 уровней, а небольшой модуль в 5-10 строк превращается в кашу из 100 строк каментов?
   Джинн
 
13 - 02.12.20 - 16:16
(12) Мне проще - я "хозяин" конфигурации и комментарии отделяют "типовой" код от измененного. Если я переписываю свои куски, что в них всегда "финальная" версия. История изменений мне не интересна. Собственно из задача в том, чтобы при сравнении/объединении отделить агнцев от козлищ.
   pudher
 
14 - 02.12.20 - 16:19
(13) Кустарь и есть кустарь :)
   fisher
 
15 - 02.12.20 - 16:20
(11) В гит в основном зеркалят из хранилища из-за git blame, чтобы быстро можно было расковыривать кто/когда.
Но если это надо от случая к случаю, то и в хранилище вполне терпимо после появления "быстрых" опций анализа (те, которые "Выборочно")
   Вафель
 
16 - 02.12.20 - 16:44
комменты внутри кода рано или поздно превращаются в такую кашу, что лучше бы их не было
   1Сергей
 
17 - 02.12.20 - 16:55
Если в типовой код внесены изменения (Пользуем расширения, но иногда приходится), то они обрамляются комментариями типа 

// Иванов И.И. 02.12.2020 тикет 0123456 {

... тут код
// } Иванов И.И.


если на форме есть изменения, внизу кода формы в таких же каментах перечисляется что именно изменили.
   H A D G E H O G s
 
18 - 02.12.20 - 17:01
Камментю только что то реально запутанное.
ДельтаПравки можно найти сравнением храна.
Камменты по стандартам Совместимо, все равно потом их суко править
   Креатив
 
19 - 02.12.20 - 17:38
Про комментарии у меня одно правило:"Никаких правил!"
Изредка комментирую те места в коде, где смысл условий не очевиден.
   mikecool
 
20 - 02.12.20 - 17:43
(19) если комментируешь код - значит твой код не оптимален и его можно и нужно переделать
   1Сергей
 
21 - 02.12.20 - 17:43
(20)

// Я не виноват - меня заставили!!!
   PuhUfa
 
22 - 02.12.20 - 17:56
Комментирую
//===== Доработка начало =====

... тут изменения/добавления
//===== Доработка конец =====


Если нужно поправить строку(ки) типового когда, то делаю копипаст оригинального куска и в нем правлю. Оригинальный кусок коменчу. Делаю так что бы потом можно было сразу понять что именно изменял.
По ходу своего кода, делаю для себя комментарии, что и для чего делается в этом месте. А то потом даже сам забываю для чего это написано.
Так как работаю один, ФИО даты и т.п. не пишу -)
   GreyK
 
23 - 02.12.20 - 17:59
А я не комментирую, я метки ставлю, типа "здесь был Я" :)
   Smallrat
 
24 - 02.12.20 - 20:39
“Code is like humor. When you have to explain it, it’s bad.”
   mkalimulin
 
25 - 02.12.20 - 20:44
(0) Я комментирую, пока нахожусь в процессе разработки. По мере того, как отдельные куски делаются, комментарии убираются. В готовом модуле комментариев нет. Очень удобно. Раз глянул и сразу видишь: здесь все готово или нет, есть еще зеленого мальца
   Джинн
 
26 - 02.12.20 - 21:19
(20) Если Вы работаете с типовой, то хорошее комментирование своих изменений снижает трудозатраты на обновления в разы.
   olegi3007
 
27 - 03.12.20 - 01:49
(22) также делаю, но еще и добавляю свои инициалы и дату (г-м-ч) и время, чтоб потом понять что я сначала делал, а что потом доделывал...
Вообще в 1С (да и в любом другом языке) суть кода должна быть в основном ясна из названий переменных и процедур-функций... Если код нужно много коментить, то это не есть хороший код... Разве при вызове ф. или п. не понятно зачем и почему именно это, то имеет смысл коротенько написать... Как-то пробовал на php прокоментить почти каждую строчку... ужас, очень сложно потом читать.... отказался от этого дела... обычно ставлю короткие коменты и то на время, типа: "// для отладки" " // пока не доработал"... это помогает... только их писать надо однообразно, чтобы искать потом можно было...
   prog1Csww
 
28 - 03.12.20 - 03:23
// Начало измененного блока

...
// Окончание измененного блока


...// Начало и окончание измененного блока


Раньше делал через шаблоны автоподстановки.
   MadHead
 
29 - 03.12.20 - 05:48
Когда-то услышал фразу
"Комментарии- это извинение за плохо написаный код" )
   Paint_NET
 
30 - 03.12.20 - 05:54
Когда кодил, пользовался таким подходом - оригинальную процедуру/функцию оставлял на месте, копипастил её в свой модуль с префиксом (к примеру, изм_ОбменДаннымиСервер), там её правил, как мне надо и менял вызовы исходной процедуры на обращение к этому модулю. В самом модуле перед функцией делал развёрнутый комментарий с перечнем изменений, при необходимости его дополнял с датой и причиной.
 
 Рекламное место пустует
   Paint_NET
 
31 - 03.12.20 - 05:55
(29) Согласен. Хорошо структурированный код с правильно именованными переменными, процедурами и функциями не нуждается в комментариях.
   Mikhail Volkov
 
32 - 03.12.20 - 06:54
(30) > при необходимости его дополнял с датой и причиной.
Свою метку и дату ставлю всегда при внесении своих изменений в исходном коде, чтобы не затерлись обновлениями. Но когда изменения не более двух строк. Если больше, то вставляю свою функцию или процедуру. Которую вызываю из своего общего модуля. В нем при необходимости пишу нужные комментарии.
   МимохожийОднако
 
33 - 03.12.20 - 07:45
Важно научиться читать чужой код без агрессии и нервотрепки. Свой код читать при этом как чужой.
   toypaul
 
34 - 03.12.20 - 08:00
Похоже большинство не совсем правильно поняли суть проблемы. Суть не в том как вы расставляете плюсики/минусики или фигурные скобочки. Вопрос в том как избавляться от мусорки, в которую превращается код от бесконечных каментов.

Я работаю, например в конфе, в которой каменты как минимум с 11 года. Иногда встречаются и с 04 года. В итоге на одну строчку кода бывает 10-20 строк каментов. Учиться читать такой код? Да упаси боже. Душевное здоровье дороже.

И по всей видимости это болото незаметно затягивает любого кто в него наступил. Сначала ты учишься читать чужой код, а потом сам незаметно превращаешься в этакого 1С-ника Голума :)
   pudher
 
35 - 03.12.20 - 08:04
(34) Я если вижу комменты старше 1 года, их просто убираю. Никому они не понадобятся 100%.
   Галахад
 
36 - 03.12.20 - 08:05
(34) Кровавый энтерпрайз. :-)

Решение. Переход на новую систему...
   Mikhail Volkov
 
37 - 03.12.20 - 08:15
(34) > Вопрос в том как избавляться от мусорки, в которую превращается код от бесконечных каментов.
Делай также (32), минимальные изменения исходного кода.
   Paint_NET
 
38 - 03.12.20 - 08:21
Либо как в (30). Плюс практически все доработки будут в твоих отдельных модулях, что может пригодиться в будущем.
   Галахад
 
39 - 03.12.20 - 08:29
(37) (38) Как этом можно сделать, когда  задача оптимизировать код? Например снизить время операции.
   Bigbro
 
40 - 03.12.20 - 08:30
я не удаляю старые комментарии и закомментированные куски кода, даже когда они начинают занимать половину текста.
потому что даже через несколько лет иногда встает вопрос - а почему именно так, и как было тогда то.
по истории можно восстановить картину с тем как модуль работал 2, 3 и 5 лет назад, как менялся и по чьим заявкам.
в итоге бывает приходят к тому что все вот это нам теперь не надо - верни как было в 2008м, только одну штуку добавь и все.
без комментов было бы невозможно реализовывать такие хотелки.
   Paint_NET
 
41 - 03.12.20 - 08:33
(39) Каким образом описанные схемы увеличивают время операций?
   Масянька
 
42 - 03.12.20 - 08:39
В универе с первого курса преподы говорили: "Комментируйте свой код."
Полностью согласна.
В зависимости от задачи: бывает достаточно одной строчки (описания), бывает нужно больше.
   Галахад
 
43 - 03.12.20 - 08:39
(41) Никаким. Вопрос каким способом можно оптимизировать время, если отдельные процедуры уже в принципе нормальны.
А оптимизацию можно сделать, только через какой-то новый подход.
   МимохожийОднако
 
44 - 03.12.20 - 08:40
(34) Если это мусор, то его надо выкинуть. Это очевидно. Если сомневаешься, то перебирай этот мусор аккуратно и без брезгливости.Это твоя работа.
   Малыш Джон
 
45 - 03.12.20 - 08:45
(34)Скопируй кусок кода с мусором ниже, старый кусок полностью комментируй(можно в область завернуть: потом сворачивать можно, чтоб глаза не мозолил), из нового куска удаляй весь мусор (да и, как правило, за такое время мусор не только в комментариях, но и в коде есть; его тоже полезно почистить). Если через год старый закомментированный кусок никому не понадобился - смело удаляй.
   Масянька
 
46 - 03.12.20 - 08:45
+ (42) Если в одном блоке (по смыслу) получается больше двух-трех (по ситуации) комментов - полностью ремарю исходную.
   Paint_NET
 
47 - 03.12.20 - 09:04
(43) Так если оптимизируем, то так же и делаем. Оставляем оригинал, делаем его копию и там оптимизируем. Ничего страшного в том, что после оптимизации в конфе останется неиспользуемый код, нет. Зато, повторюсь, все доработки будут вне базовой конфы в одном месте лежать, что очень удобно.
   toypaul
 
48 - 03.12.20 - 09:18
(37) я так делаю иногда с запросами. потому что все эти каменты в запросах это полный бред с точки зрения поддержки. но вот недавно сказали - не надо так делать. потому что в моей новой процедуре не видно что именно было изменено.
   Ёпрст
 
49 - 03.12.20 - 09:31
(0) каменчу только то, что самому нужно, а так , не каменчу ничего.
   ptiz
 
50 - 03.12.20 - 09:53
Главное, писать не только то, что делает код, но также "зачем", и "по чьей хотелке", и "почему поменяли обратно".
   spiller26
 
51 - 03.12.20 - 10:14
(0)
//--> Фамилия И.О. (контора если нужно), дд.мм.год, № задачи

// основной код
мой код
//<-- Фамилия И.О. (контора если нужно), дд.мм.год, № задачи 


Старый код удаляется, если не нужен, или ставиться условие дата до какого момента он должен работать.

Ненавижу:
- когда в условиях ставят конкретного пользователя типа "Если пользователь = "Пупкин" Тогда ..."
- свои реквизиты, справочники, доки и т.д. называют стандартно без дополнительных обозначений. (я ставлю пару букв и "_", например "ссс_НазваниеОбъекта")
   aka MIK
 
52 - 03.12.20 - 10:26
(0) есть же хранилище. комменты старше пары лет можно безболезненно чистить - обработку бы еще написал кто-то..
   aka MIK
 
53 - 03.12.20 - 10:27
(51) это неправильно, формат даты должен быть год.мм.дд, иначе не найдешь изменения, сделанные "примерно в прошлом месяце"
   aka MIK
 
54 - 03.12.20 - 10:28
(25) переучивай потом таких..
   Bigbro
 
55 - 03.12.20 - 10:33
(50) именно так. важно понимать почему и для чего именно таким образом работает модуль. а комменты к самому коду - имхо нужны, только когда что-то совсем нестандартное наворачивается. остальное должно быть и без комментариев читабельно и прозрачно, для нормального кода.
   spiller26
 
56 - 03.12.20 - 10:35
(52) Хранилище может умереть, многие не пользуются хранилищем.
   ДенисЧ
 
57 - 03.12.20 - 10:38
(56) Умереть может кто угодно. Н, в отличие от человека, хранилище можно ежедневно резервнокопировать
   aka MIK
 
58 - 03.12.20 - 10:42
(56) умереть может, это да, но можно хранить бекап cf с этим всем мусором до чистки.
   Ботаник Гарден Меран
 
59 - 03.12.20 - 10:46
Когда рвал БП в лоскуты в одну харю, то комментировал как в (9) примерно. 
//+=

Здесь мой код
//+-

Вся строка добавлена мной//++

//Типовой код//--


Потом влился в большие коллективы и комментирую по принятым правилам
//((Банда погоняло дата номер приказа

Мой код
//))Банда погоняло дата номер приказа
   Timon1405
 
60 - 03.12.20 - 10:57
(15) +1 за git+blame. в самом коде только подробости по неочевидным строкам кода. по любой строке кода можно мгновенно(!) получить историю (никаких нудных открыть версию конфигурацию в хранилище, сравнить с текущей и пр.)+ пишем в "коммите" в хранилище номера задач в трекере - подробности по задаче смотрим там.
 
 Рекламное место пустует
   aka MIK
 
61 - 03.12.20 - 11:08
(60) да уж, поднимать историю в стандартном хранилище - это ад
   kumena
 
62 - 03.12.20 - 11:45
Никогда не понимал комментариев с надписью в стиле "Здесь был Вася, такого то числа, такого то года". Потом приходит Петя, и пишет что он тоже здесь был, но позднее.
А еще позднее Федя, пытается разобраться что-же делали Вася и Петя, которых уже давно нет и найти нельзя. И толку от этих комментариев? Получаем ситуацию как у автора.

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

По хранилищу можно найти все изменения, а если указывать там всю нужную информацию, то все очень удобно.
У меня на прошлом месте работы после внедрения изменений была рассылка изменений хранилища пользователям и команде разработчиков, чтобы все видели какие проблемы/заявки исправлены.
   kumena
 
63 - 03.12.20 - 11:47
> да уж, поднимать историю в стандартном хранилище - это ад

Какие сложности?
Правая кнопка мыши на объекте - История объекта. Все, весь лог изменений перед вами!
   NWsFF
 
64 - 03.12.20 - 12:21
В коде убираю все комментарии, оставляю только те что над процедурами/функциями
   aka MIK
 
65 - 03.12.20 - 13:10
(63) и как найти кто изменил конкретную строку?
   xenos
 
66 - 03.12.20 - 13:57
//{имяфранча

//задача: описание задачи (описание в нескольких местах должно совпадать до символа,чтобы искать по разным модуля, или номер задачи в хелп деске)
//иванов - кто делал

//2020 12 03
//прим. - примечания, заказчик

//{убрано
///.... убраный кусок кода

//убрано}
//{добавлено

Новый код
//добавлено}

//имяфранча}
   Малыш Джон
 
67 - 03.12.20 - 14:01
Первое правило по комментированию кода: никому не говорить про комментирование кода.


Список тем форума
Рекламное место пустует  Рекламное место пустует
ВНИМАНИЕ! Если вы потеряли окно ввода сообщения, нажмите Ctrl-F5 или Ctrl-R или кнопку "Обновить" в браузере.