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

Итак, все Вы(Мы) когда нибудь, кто редко, кто часто, а кто постоянно вынуждены вмешиваться в код написанный сторонними разработчиками. И зачастую это вмешательство бывает разовым, т.е. код и дальше будет поддерживаться предыдущим (а может быть и новым) "творцом"...
Так вот, правила приличия подсказывают что, такого рода вмешательства должны быть должным образом прокомментированы. И что желательно, но как показывает практика совсем не обязательно, комментарии эти должны содержать не изречения Капитана Очевидности, а краткую суть и(или) предысторию, приведшую к возникновению комментируемых изменений.
Все это понятно.. вопрос в следующем:
Подскажите самый правильный (лучший, идеальный) способ обрамления своих изменений кодом.
Я на сегодняшний день использую такую конструкцию:

// [начало] mvgfirst 15.04.2012
// пояснительные комментарии

// ... тут я комментирую код который был до внесения мною изменений

.... тут как правило идет код который я добавляю

// [окончание] mvgfirst 15.04.2012

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

просто без слоев выглядят комменты как зоопарк

где есть (можно посмотреть слои) ?

особенно когда закрывается одна-две строчки кода а нам и под жирная конструкция кодера

(56) это одноэс должна была давно реализовать

(58)
где реализованы слои ?

(0) сейчас так пользуюсь
//:псевдоним - описание действий
//:псевдоним

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

комменты часто пишу когда код замудренный получается и через полгода сам будешь думать что понаписал :)

зачем комменты нужны ?

(59) наверное (jsmith) где-то видел
я не помню может и сам видел но мысля такая давно сидит

еще есть мысля что реквизиты объектов конфигурации были ссылочными
тогда их легко будет найти и обработать

(61) имхо когда код мудренный - комменты помогают
если таких конф не писывал то да комменты кажутся чем-то ненужным

коментирую редко, но обычно в таком формате

//-----------------------------------------
// vde69, замена кода
// было:
//
// бла-бла
//
код
// vde69, конец замены кода
//-----------------------------------------

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

(64) имелось в виду именно исправления в чужем коде..

смысловых коментов пишу много

В кацапте есть слои

слышал, нуралиев обещал в 8.3 их появить

(63) пиши правильно -комментировать ненужно

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

(1). О, сразу видно тру программера. Нафиг нужны эти комменты, отнимают только время. :)

в принципе, что слойность реализовать (тем более для интерпретируемой системы) много ума не надо
странно, что разработчики до сих пор не сделали

(69) я ждал этого коммента :)
спорить не буду - вариантов реализации алгоритма может быть несколько
и каждый прог свой вариант считает правильным ;)

если так проще меня понять
комменты в моем коде для меня являются некими метками по которым я якорю эти куски кода в голове
чтобы быстро ими быстро оперировать когда возвращаюсь к этому коду
грубо говоря это все равно что сворачивание кода в одну строку-описание

(73) т.е. ты обычно не помнишь о чём ты размышлял ?

(71) скорее тру-кодера после которого хоть потоп
и к своему коду из одного цикла он не возвращается )))

(0)

При изменении типовой конфигурации предпочтаю такой способ:

Для добавления нового кода
// ВечныйНуб {+
..
// ВечныйНуб +}

Для закомменчивания неверного типового кода
// ВечныйНуб {-
//
// ВечныйНуб -}

кому-то, может, комменты и не нужны, а мой слабенький мозжечок не может запомнить те 80 изменений, что я тащу при обновлениях из одного типового релиза в другой

(74) первые полгода помню, но конф много...
при универсиализации кода он становится менее понятен чем прикладной код но задупленный много раз конечно
я терпеть не могу дуплить код

(72) может не хотели раздувать конфу... ну можно было бы дать потом кнопку типа - оставить только актуальный слой
одноэс мне напоминает подход виндовс
когда можно сделать вменяемый проигрыватель музыки\видео они оставляют это на стороннего разработчика

(76) и еще отдельный текстовичек где прописаны изменения типовой ?

(76)
Изменения в коде в отдельном текстовичке не нуждаются: тупо выполняю полный поиск по вхождению моего ника, после чего вижу все изменения.
Но текстовичок таки есть. Там изменения "не в коде". Т.е. то, что при обновлении беспощадно замещается (например, роли и интерфейсы).
Есть у меня, к примеру, новый регистр. И после каждого обновления, если в типовой изменились роли, мне надо не забыть заново дать бухгалтеру право на запись в этот регистр. Может, есть способ объединения ролей, просто я не знаю?

(79)
сорри ) ответ в сообщении (80)

(0) Пишу так: "Старый вариант. Закомментил я, дата ". Комментирую и сохраняю старый код. На новый код пишу "Новый вариант. Добавил я, дата"...ну и плюс описания кусков(если надо). История изменений в некоторых конфигах отслеживается с 2008г...

(80) как вариант роль-клон но не исключает что исходную роль сильно поменяют

У нас комменитруют по такому шаблону:

// Моя вставка <?"", ИмяПользователя> <?"", ДатаВремя, "ДФ=dd.MM.yy">
// Конец моей вставки

(0) код надо писать так, чтобы понятно было, что он делает и зачем, уже из самого кода. Твои зеленые простыни нафиг ни кому не нужны, ибо в правильном коде они излишни, а говнокод они не спасут

(85) фотку лучше смени )) пока тебе веры нет что 22 ))

(86) чо?..

(87) пацан справа намекае... извини ничего личного ))

(85) несогласен - комменты полезная вещь и код бывает "неодноцикловый"

(88) он в фотографа играет. Да всё нормально - я понимаю, что трудно жить, когда вся информация тобой воспринимается через призму содержимого трусов.

(90) я прекрасно воспринял оба варианта интерпретации жеста ребенка ;)
просто благоразумнее в современных реалиях фотку сменить
ну как хочешь... я ж сказал лично мне все равно

а пацаны классные - у меня только дочка пока

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

(92) глянул фотку - хорошая дочка :-)

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

(94) мая прелесть :))

чудОчка)
http://i068.radikal.ru/1204/9f/0059cf722034.jpg

(95) я не программист, но когда меня учили кодить на 1С попросили запомнить одно правило "код - для которого нужен коммент - плохой код"

(0) Очень смешно выглядят 4-5 строчек комментария на 1 строчку кода. Через пару месяцев зелени комментариев становится больше чем кода. Бывший коллега там любит писать.

(98) я начинал программировать не на 1С - может в этом дело

Комментарии

Расставляйте комментарии по принципу “чем больше, тем лучше” — пройдёт некоторое время и вы забудете, что делал тот или иной программный блок. Вообще принято комментировать код на английском языке или не комментировать вообще, так как в русском дикое количество кодировок, да и вообще так исторически сложилось. Плюйте на это, код вы комментируете в первую очередь для себя, а не для других! А раз уж вы делает это для себя делайте это в удобной для вас кодировке.

отсюда
http://www.softtime.ru/info/articlephp.php?id_article=28

(98) плохое правило. Новые функции и процедуры необходимо комментировать, и внесенные изменения также необходимо сопровождать своими инициалами и датой. А то потом не отыщешь концов.

http://habrahabr.ru/post/125545/
http://info-comp.ru/programmirovanie/177--style-coding.html

(101) зачем что-то искать? Взглянув на код - все должно стать предельно ясно. Если код требует коммента - меняйте код и меняйте его до тех пор пока необходимость в комментах не исчезнет.

еще комменты это вежливость программиста по отношению к коллегам

А версионирование по типу Википедии - может даже легко бы могли в 1С организовать...

(104) Возможен стиль, когда код комментирует сам себя (например множество исключительных ситуаций, подробная печать сообщений). Тогда еще и пользователь сможет разобраться в том что происходит, если что-то пошло не так.

(99)У меня есть обработка обмена с базой с совершенно отличной от 1с логикой учета. Выгрузка на стадии тестирования еще. Наверное у меня там комментов больше, чем кода, я местами туда выдержки из совещаний вставляла, чтобы помнить - почему решили так и кто именно учавствовал в обсуждении.

(107) приводи тогда пример

и номер заявки с ХД тоже в комменты можно
так сказать ссылка на сущность по которой сделаны изменения

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

(108)Какой пример? Пример комментария? Зачем вам :) Там тупо стенография обсуждения. Не листами, конечно, но строк по 5-6.

В той же обработке есть одно место... Тонкое очень... Начинала писать не я. И вот как-то вдруг подумалось мне, что не правильно это место работает. Взяла ручку, стала рисовать схему. Дохожу до конца, а там коммент:

//*Соколова* проверила 2 раза. Ошибок нет!

Ну... увеличила счетчик проверок :)

я всегда пишу так //***ШО 15-04-2012 и заканчиваю //***шо 15-04-2012

иногда путаюсь и пушу так:  //*** ШО 15-04-2012 и заканчиваю //*** шо 15-04-2012

(103)Глупость это.

(98)Кто-то тебе бред сказал, а ты и повторяешь не думая...

(113) глупость - это писАть код в кототом можно разобраться лишь при наличии коментов.
(114) Когда научишься писАть нрмальный код (а не ....) - только тогда тебе придет понимание того,что умные люди говорят.

(0) использую комментирование, чтобы отделить свой код от типового и потом легче было-бы найти свою писанину. Опытным программистом себя не считаю.

(0) IMHO, комменты нужны. Там должны быть максимум 4 вещи - "Кто", "Когда", "Нафига" и старый вариант кода (чтобы откатить было легко). Типа так:

// mvgfirst 15.04.2012
// Старый код сбоил на PostgreSQL, падла
// Процент = Параметры.Ссылка.Процент;
Выборка = Запрос.Выполнить().Выбрать();
Если Выборка.Следующий() Тогда
  Процент = Выборка.Процент;
Иначе
  Процент = 0;
КонецЕсли;

// mvgfirst 15.04.2012

Сам код описывать не надо. Он и так на русском.

P.S. Конечно, об это Вы не спрашивали, но если будет время, загляните сюда:
wiki:Перфекционизм_(психология)

(115) "я не программист, но.." может быть в этом все дело?

(118)+ Зачем тогда рассуждать берешься?

(119) я не программист, но это не означает,  что я не пишу код  - пишу на 1с очень давно (благо для этого прогом быть не нужно) и поэтому могу судить нужны коменты или нет.
Коменты нужны в коде:
1.  Который хрен знает, что делает потому как написан хрен знает как на несколько страниц в котором без бутылки не разобраться.
2. Исключительные ситуации когда обходится какая нить ошибка платформы либо описывается какая нить дебильная ситуация нашего законодательства - которая не поддается никакому логическому объяснению.

Изначальная строчка: Если Ы=Й Тогда Х
После правки: Если Ы=К Тогда Ю.
Как комментить будем?: //Петя из города Заступинск 01.01.2001 Изменил условие потому что тот кто это написал кг/ам...
?
Для себя комменты писать - это одно(как правило - не нужно, ну иначе если что то черезкитайское и хрен потом вспомнишь на вскидку, учитывая русский бизнес: "Сроки - вчера"). Когда человек пишет комменты заботясь о других - это другое.
Есть шаблоны. "//Петя из города Заступинск 01.01.2001" достаточно набрать один раз.

(120) странно... если способен преобразовать алгоритм в последовательность машинных команд то программист
а то ни то ни се... вроде пишешь код но не прог

Комментирую

//+ МурЬка

изменения

//++ МурЬка

При необходимости внутри блока изменений - комментарии по делу

(122) прог - тот кто знает какой-нить язык программирования. Я разработчик на 1С не более того.

(124) разработчик 1С тоже неплохо, потому что чисто программер - 1С может и не потянуть

(124)Странные рассуждения... каша у вас в голове...

раньше как-то комментировал. а теперь лень.

скоро свою нетленку на базе УГ11 надо будет передавать другому... как он там разберется?:)

(0) А вообще - умение разобраться в чужом некомментированном коде есть своего рода тест на профпригодность. Для меня еще с семерки с этим проблем не было. Естьже сравнение конфигураций в конце концов :)

(128) будет поминать добрым словом если отличит от типовой
к слову еще в семере баги старых прогеров отлавливаются
а им пох

(129) сравнение каких конф ? типовой и дописанной ?

(117) а в этом, пожалуй, что-то есть...

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

(131) да :)

(115) Вообще-то умные люди утверждают несколько иное:
"Good comments don't repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do." Steve McConnell. Code Complete

(126)ты не можешь в коде разобраться без коментов (писАть код так, что бы он был понятен без коментов) а каша в голове у меня - класс.

(136) Это всего лишь вопрос времени. В хорошо документированном коде (не путать с избыточно документированном) разбираться быстрее, при прочих равных.

(136) точно :) два раза у меня было: расходился с клиентом по вопросу цены сопровождения. он брал другого прогера, который начал ругать мой код типа некомментирован, что писатель из меня 1сный фиговый и т.д. Клиент при этом многозначительно при расставании смотрел на меня. Первый позвонил через два месяца второй через полгода. Второго послал ибо я ему вернул половину суммы, и сказал что мое возвращение стоит этой возвращенной суммы безвозвмездно. Чего там эти горе программисты налопатили до сих пор вспомнить страшно :))

Так что если прогер дебил ему и комменты не помогут, а если спец он на них особо внимания и не обратит.

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

(138) Ещё одна полезная вещь - журнал изменений, где написано, что делалось, когда и зачем - вот с ним гораздо проще понять, что было сделано.

(137) вот именно. времени много не бывает тем более разбираться в чужих творениях
у куска кода есть определенная функция - если она обозначена, то углубляться в структуру кода необходимо только если код с багами или его приходится дописывать

в общем-то понятно
и без автора конечно можно разобраться, но подход его - "пишем только раз" - не делает его профессионализму чести

(135) интересно ты на англоязычных форумах пишешь на русском?! (вопрос риторический, перевод не требуетсяятнт).
(137) Возможно в серьезных языках и требуется что-то описывать - в 1Ске все на русском -чего тут комментарить то?
Вот зачем тебе коменты? Правильно - чтобы разобраться в коде в котором вообще ничего не понятно.

а если несколько изменений одного участка разными датами, что пишете?

Я примерно также далаю как 0
Дополнительно, если вставляю свои переменные, обработки, функции, то впереди ставлю псеводним.
Правда обычно псевдоним не свое ФИО, а название организации, кому принадлежит база.

(0) Это удобно только при разовых изменениях в чужом коде при отсутствии системы контроля версий. Вернее, не то чтобы удобно - вынужденная мера.
При нормальной совместной разработке все вопросы разруливаются системой контроля версий, а комментится только логика. Иначе не код получится, а форум какой-то и все равно нифига не разобрать будет.

Я делаю так

//++ %UserName% %Date%
// Comments

//Было ...

Стало

//--

(0)
//Я
// old_code
...new code
//я

(144) Речь о системе контроля версий не идет. Вопрос подымается исходя из реалий работы фрилансера. Когда ему достается база (конфигурация) в которой нужно разобраться, внести изменения и отдать заказчику. Да так что бы не было стыдно перед последователями не только за качество кода, но и за его документирование.
P.S.
А процедуры длиной в несколько экранов выводят из себя настолько что ни один грамотный комментарий не поможет. Единственный вопрос возникающий в этот момент в голове - "... неужели он(она/оно) не знает о том что можно создавать процедуры и функции и вызывать одну из другой...
Особенно прикалывают конструкции Если Тогда КонецЕсли у которых между началом условия и окончанием экранов так 5-6 и множество вложенных условий.

(147) Есть же жадные лохи еще на свете, с фрилансерами связываться :)

(148) Какая связь между жадностью и обращением к фрилансеру?
Т.е. если человек, считает себя профессионалом и не желает идти в кабалу в какую-то франч-фирмочку... то он обязательно должен работать за гроши...?

(149) Все хорошо. Будь свободным.

Когда пишу свое - комментирую редко, где реально нетривиально что-то, что может сбить с толку. Если и камменчу - не больше чем в одну строку. А если правлю чужой код - отделяю, и ставлю дату и имя обязательно.

(147) Ну так я об этом и говорю.
"удобно только при разовых изменениях в чужом коде при отсутствии системы контроля версий"
Где тут противоречие?

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

(147) а в типовых разве не так?