Комментарии при разработке #116645

В общем смысл вопроса приблизительно такой: Какие требования к комментариям (у вас) ставит работодатель? Столкнулся с проблемой что не могу понять чего от моих комментариев хочет работодатель. На вопрос - дайте посмотреть пример оформления работы? - не реагирует. (просьба к тем кто будет отвечать в теме - вставляйте куски кода с комментариями, не более 1-2кб с основным комментарием в заголовке модуля и несколькоми комментариями по тексту программы, как примеры).

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

Нет они комментарии разрабатывают ;)

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

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

Твой личный бред... имеешь полное право на него...

Пару раз проверят, премии лишат - на всю жизнь запомнит как и почему надо код комментировать

Любой русский программист, после пары минут чтения кода, обязательно вскочит и произнесет, обращаясь к себе: переписать это все нафиг. Потом в нем шевельнется сомнение в том, сколько времени это займет, и остаток дня русский программист потратит на то, что будет доказывать самому себе, что это только кажется, что переписать это много работы. А если взяться и посидеть немного, то все получится. Зато код будет красивый и правильный. Hа следующее утро русский программист свеж, доволен собой и без единой запинки докладывает начальству, что переписать этот кусок займет один день, не больше. Да, не больше. Hу, в крайнем случае, два, если учесть все риски. В итоге начальство даст ему неделю и через полгода процесс будет успешно завершен. До той поры, пока этот код не увидит другой русский программист. А в это время, в соседних четырех кубиках, будет ни на секунду не утихать работа китайских программистов, непостижимым образом умудряющихся прийти раньше русского программиста, уйти позже, и при этом сделать примерно втрое меньше. Эта четверка давно не пишет ничего нового, а только поддерживает код, написанный в свое время индусом, и дважды переписанный двумя разными русскими. В этом коде не просто живут баги. Здесь их гнездо. Это гнездо постоянно воспроизводит себя при помощи любимой китайской технологии реиспользования кода - copy/paste. Отсюда баги расползаются в разные стороны посредством статических переменных и переменных, переданных по ссылке (ведь, китайский программист не может смириться с неудобствами вызванными тем, что он не может изменить значение внешнего параметра). Вспоминая об этих переменных и ссылках, русский программист, как правило, на время теряет дар английской речи, и переходит к какой-то помеси русского и китайского. Он давно мечтает переписать весь ! кусок, над которым работают китайцы, но у него нет времени. Он уже переписывает два больших куска, и доказал начальству необходимость переписать третий. Кроме того, русский программист боится обидеть китайцев. Они могут решить, что он пытается вытеснить их с работы. К слову сказать, напрасно боится, поскольку китайцы уже так решили. Hа китайцах висят серьезные баги, о которых знает начальство и постоянно их торопит. Китайцы уважают начальство и потому перевешивают баги друг на друга очень торопливо. Они знают, что все попытки починить приведут к появлению новых багов, еще худших. И в этом они правы. Разобраться в том, в каком порядке меняются статические переменные, и как приобретают свои значения, способен только один человек на фирме - индус. Hо он пребывает в медитации. Поэтому, когда всю четверку уволят во время сокращения... А кого еще увольнять? Русский - еще не переписал свой кусок, а индус - главная ценность фирмы - он редко обращает внимание на проект, но когда обращает, все понимают, что так как он, архитектуру никто не знает. Так вот, когда китайцев увольняют, у их кода возможны две основные судьбы. Первая - он попадет к русским, и его перепишут. Вторая - он попадет к местному, канадскому программисту. О, канадский программист это особый тип. Он, ни на минуту не задумываясь, как рыцарь без страха и упрека, бросится фиксить самый свирепый баг китайского кода. Этот Баг живет там уже три года, и китайцы уже четырежды (каждый по разу) сообщали начальству, что он пофиксен. Hо Баг каждый раз возвращался, как Бетмен в свой Готхем. Итак, канадский программист, воспитанный на героической патетике американского футбола - бросаться в бой головой вперед, сделает то, чего китайцы не рисковали делать в течении трех долгих лет. Он, при помощи дебагера, отследит место, где статическая переменная приняла значение -1 вместо правильного 0, и решительным движением заведет рядом вторую переменную с правильным значением. Баг погибнет в неравной схватке с героем. Hо победа будет достигнута тяжелой ценой. Работать перестанет все, включая только что переписанный русским программистом код. Это повергнет русского программиста в задумчивость на целых два дня, после чего он сделает, в общем-то, предсказуемый вывод о том, что дизайн с самого начала был неправильным, и все надо переписать. Hа это нам нужна неделя. Да, неделя, не больше. Канадский программист смело бросится налаживать все, и станет еще хуже, хотя казалось бы... Эта суета выведет из медитации индуса, который придумает и вовсе гениальное решение - отбранчить код. Согласно его плану, мы теперь будем поддерживать две версии одного и того же кода - одну работающую, но с Багом, другую без Бага, но не работающую. Русский программист, услышав об этом плане, сломает линейку об стол и обзовет жену дурой, но на митинге возразить не решится. К счастью, все это не сильно влияет на дела фирмы, поскольку продукт продается и так. Поэтому менеджмент ходит в целом довольный и не устает напоминать всем, что они отобраны как лучшие среди лучших. И что мы давно доказали свою способность выпускать продукт тем, что выпускаем его иногда.

лиши человека пару раз премии он уйдет куда подальше.

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

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

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

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

ты посадил фирму на иглу... Если уйдешь - фиг кто разберется в твоих творениях... P.S. даже при правильных названиях функций...

Вот именно этого работодатель и боится...

Не знаю у меня без комментариев не получается, привык я к ним. Хотя переменные и функции называю осмысленными именами

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

переучивайся. Комментарии нужны.

они у меня есть на сложных участках. а в повседневности смысла не вижу. Нафига мне коммент //Выводим секцию Текущий документ. практического смысла в этом не вижу, только мусор.

Рекомендации по комментированию кода на Дельфи, вполне применимые к 1С: Существующие типы комментариев: пояснение сложного (изощренного) кода – очень часто при решении определенных задач (особенно критически важных по скорости работы) не удается избежать использования алгоритмов, которые очень сложны для понимания – в данном случае только подробный комментарий позволяет разобраться, как функционирует данный код; маркеры – маркеры обычно используются программистами для временных целей, когда нужно отметить отладочные команды или незаконченные фрагменты кода; когда проект завершается, маркеры и, при необходимости, сопутствующий им код, удаляются; разделители – в современных проектах размеры исходных файлов могут быть чрезвычайно большими, и для того, чтобы помочь в отделении структурных частей кода также могут использоваться комментарии; обычно в комментариях подобного типа применяются повторяющие символы (-, =, # и др.), чтобы сделать форматирование более наглядным, однако в данном случае не рекомендуется использовать символ "*"; резюмирующий код комментарий – этот тип комментария поясняет, каким образом работает код и позволяет без вникания в детали реализации понять алгоритм работы; обычно данный комментарий помещается вначале структурного блока кода (модуля/класса/метода/процедуры/функции и т.д.) и его значимость существенно увеличивается одновременно с ростом размеров кода; описание использования кода – данный тип комментария предоставляет информацию, каким образом использовать определенные переменные/процедуры/функции и т.д. и обычно помещается перед ними; данный тип комментария может содержать дополнительную информацию относительно особенностей функционирования кода, например, возможные "побочные эффекты"[4]. Общие соображение по использованию комментариев могут быть следующими: помещайте комментарий недалеко от начала модуля для пояснения его назначения; помещайте комментарий перед объявлением класса; помещайте комментарий перед объявлением метода; избегайте очевидных комментариев: (i := i + 1 // добавить к i единицу); помните, что вводящий в заблуждение комментарий хуже, чем его отсутствие; избегайте помещать в комментарий информацию, которая со временем может быть не верна; избегайте разукрашивать комментарии звездочками или другими символами; для временных (отсутствующие в релизе) комментариев используйте "TODO"; старайтесь создавать, где это имеет смысл, один блочный комментарий доступный для понимания, чем множество разрозненных комментариев, разбросанных по коду и усложняющих его чтение; это особенно актуально при пояснении работы сложных алгоритмов – лучше объяснить все один раз и сразу, чем комментировать отдельные куски сложного кода; комментируйте циклы, логические условия – именно эти участки кода являются ключевыми при его изучении; всегда комментируйте исправление ошибок и сопровождающий данному процессу код; обязательно комментируйте код, влияющий на изменение интерфейсов, поведение объектов и т.д. – любые внутренние изменения, которые влекут за собой изменение работы со структурными единицами кода извне, должны быть закомментированы; комментируйте завершающий end структурных блоков программы, которые не помещаются на один экран при просмотре (например, циклы, условные проверки, оператор case).

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

Для: Да, а как ещё? Для: Есть конечно и такое, что программист не может хорошо и правильно описать что он делал. Но где такому специалисту выдавали диплом? На самом деле ИМХО это не большая проблема и комментарий человека умеющего его писать будет более конкретным, объективным и достаточным в отличие от комментария того кто не умеет его сделать. Для: "комментируйте циклы, логические условия – именно эти участки кода являются ключевыми при его изучении;" В Дельфи может быть и нужно, в 1С обычно условия итак написаны на естественном языке и понятны. Лучше всё-таки описывать суть кода, его цель, чем заниматься комментированием каждой строчки - это основной принцип. В общем я так понимаю никто в 1С нормальных комментариев не делает (использование основных и дополнительных сигнатур, указания стартовой информации в начале модуля, выполнение работ по регламенту и т.п.)? Или используются комментарии местами, или вообще без них. Кто-нибудь пишет в комментариях суть кода, его идею?

(__) а я и через 5 минут, незнаю что в начале написал, так по наитию, конечно часто выходит галемотья, но рабочая... а коментарить, на счет этого хорошо сказано в какомто фильме... "...я вперед говорю, потом думаю, откуда я могу знать что скажу если еще не сказал..."

Вообще-то, если комментировать код, это будет дисциплинировать ум, будешь четко знать, чего хочешь накодить. А иначе, смотри

На вложенных циклах и условиях комментарии всегда в начале-конце делаю, на каком бы языке не программил. Жизнь научила. Что если пришлось использовать n>=4 вложенных циклов/условий и достаточно объемный код внутри, то потом неизбежно возникает "желание переписать это все нафиг", если endif-ы не отмечены дешифровкой.

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

а рекурсию как комментировать? + если еще и try...

Если скрупулезно комментировать, тем более вначале кодирования, что хочешь сделать, то просто ошибок в коде будет меньше.   Сужу по своему, хоть и не большому опыту. В том то и дело, что не всегда знаешь, что хочешь накодить.

а ты накодированный код больше никогда не читаешь? Вот когда ты его на[ш]кодил а потом правишь, тогда и ставишь комменты. Чтоб не повторять тупую работу по вспоминанию собственного хода мыслей многократно.

читаю(к сожалению), но вот кусок с комментами, и что они дадут? и как тут закоментить еси обращение к куче универсальных процедур/функций, которые в свое время также обращаются далее..., только сказать "тута я разбираю номенклатуру по техкартам", и что это даст? ... ...

Читаю. Сходу неясно дальнейшее назначение переменных ХозОперация,Спр1,Спр2,ТабН. ТабОпераций более понятна, тока потому что сразу же идет инициализация ее колонок. Это уже значит, что по дальнейшему коду я должен держать в уме имена 4 переменных и пытаться понять их смысл из логики программы, которую при первом прочтении кода я тоже пока не знаю. Хотя правильнее -- если бы я изучал логику программы, зная предназначение переменных. Отсюда вывод №1: создаваемые переменные -- комментить. Может мне и не надо знать, что делается под капотом глобальной функции. Но аббревиатуру Всп я сходу не понимаю. Поэтому мне надо либо знать, что это за переменная, либо знать, что возвращает глСвойстваСоздатьТЗСвойств(какие именно свойства). Либо на худой конец знать для чего ты результат одной некомментированной функции передаешь другой некомментированной функции, и что это дает. Т.е. я понимаю, что устанавливаются какие-то свойства, а какие именно? КонецЕсли у тебя незамкнутый. Так и неясно, какие альтернативы... Достаточно?

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

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

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

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

а правильная работа состоит в производстве не только работающих, но и ДОКУМЕНТИРОВАННЫХ программ, а не тех у которых трудозатраты на поддержку выше трудозатрат на переписывание не забуду. зачем изобретать велосипед, если уже изобретен автомобиль? тем более в хреново документированном ЧУЖОМ коде со сложной логикой без пошагового прохождения хрен разберешься. это мазохизм имхо.

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

поверь - непоможет отладчик(если конечно ситуация нетривиальная), стаж у меня еще с машинных кодов...

+ поставь отладчик на глобальный хук и посмотри что выйдет...

Замечу что дебагом тоже нигде не пользуюсь :) В обшем свели всю тему к тому как делать комментарии. Немного печально, так как услышать хотел немного другого. Неужели ни у кого из вас работающих в фирмах, разработывающих конфигурации 1С и т.д. нету регламента в котором указано как должны оформляться комментарии (регламент приложен к договору)?

вот этт верно, нужен РЕГЛАМЕНТ, если озадачат, что нужно по регламенту, то буду следовать его букве, а то "пиши чтоб понятно", как понятно - кому понятно?

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

Где-то видел общие рекомендации именно для 1С. Если вспомню, то завтра кину ссылку

Да были. На работе точно есть. Ссылки во всяком случае. Но к сожалению на работе я теперь работаю... А основные ссылки - это как нужно именовать переменные.

Нормальные имена переменных - позволяют избежать лишних комментариев. Вот одна из сылок:

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

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

На второе. ;) На первом месте как раз проблема выделения ресурсов на само создание такой документации. Для примера, не самая подробная документация одной самописной конфигурации составила 470 листов. Далеко не все в состоянии выделить столько времени и труда на это.

есть понятие "технический писатель", которое явно неизвестно в 1С

Точно не помню название документа, попробуйте поискать в сети что-то похожее на "Система стандартов и регламентов разработки конфигураций "1С:Предприятие".

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

и что выходит тоже что и в комментарии ;) А я вот незнаю ни алгоритма, ни "скелет конструкции"... Сожусь и пишу, а уж что выйдет тока богу ведомо...

Почему? Программа по разному работает в зависимости от объема комментариев? :)

А поддерживать-то людям. :)

"Почему? Программа по разному работает в зависимости от объема комментариев?" А ты попробуй набабахать в обработку кучу комментариев, а потом замерь её производительность. Да и просто редактирование модуля, где комментарии через строку - не очень-то удобно.

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

"1С:МетодикиРазработки" приложение №1 партнерского диска ИТС

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

Я бы кстати посоветовал опираться на старое эмпирическое правило: известно, что человек может удержать в памяти одновременно группу объектов 7(+/-)2 шт. Следовательно, комментирование каждых 5-9 строк в коде (в условиях конфигуратора 1Сv8 сворачиваемый цикл или условие может считаться за одну строку) в первом приближении может оказаться достаточно хорошей практикой. Естественно, при этом внутри сворачиваемого вызова также стоит правило соблюдать, рекурсивно. Такой код будет лояльным к читающему его.

для : Это конечно хорошо, но где его взять? И что такое ИТС?

Наткнулся сегодня в ЗиКе на такие комменты программеров 1С: Долго смеялся напару с бухом

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

Есть стандарты разработки от самой 1С... чего долго спорить А каменты - нужно в меру и по смыслу (не для самых тупых) Я так вообще редко ставлю... плохо, конечно (иногда что-то для себя, чтобы не забыть)

51)... "Акт записи н аобычном языке описаня того, что делает программа, и что делает каждая функция в программе, является критическим шагом в мыслительном процессе. Хорошо построенное, грамматически правильное предложение - признак ясного мышления. Если вы не можете это записать, то велика вероятность того, что вы не полностью продумали задачу или метод ее решения. Плохая грамматика и построение предложения являются также показателем поверхностного мышления. Поэтому, первый шаг в написании любой программы - записать, что именно и как делает программа" ... "Оправдание "у меня не было времени, чтобы добавить комментарии" на самом деле означает - "я писал этот код без проекта системы и у меня нет времени воспроизвести его". Если создатель программы не может воспроизвести проект, то кто же тогда сможет?" Ален И.Голуб С и С++. Правила программирования. - М.: БИНОМ.

Браво! >> зы Другой программист не должен разбираться в вашем коде. Это слишком долго. >> Проще зная что на входе и что должно быть на выходе написать свое. Должен. Если ты делаешь нормальный программный продукт, а не сиротинушку-программу, работающую только на ограниченном наборе данных и при поддержке ограниченного набора программистов :)

Книжка, что упомянута в практически моя настольная книга, хоя я никогда не писал на Си. Рекомендую.

я вот для себя как комментарии пишу :))             // отправителя на всякий случай получаем, но не понятно зачем, потому что в бух. нет деления по фирмам.

66) Лучше тогда совсем не пиши ;)

вот так еще бывает у меня :))

Требования 1С при сертификации - чтобы были откомментированы: -ВСЕ метаданные и их реквизиты -Все статические переменные (которые так любят китайцы) -Все процедуры и функции и их параметры и возвр. знач. -Сложные алгоритмы. Имхо это правильно. То есть, локальные переменные нах не надо обзывать длинными именами и комментировать. Еще я ставлю комментарий типа: Чтобы было ясно, где чей конец :-)

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

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

вот еще у меня есть такой коммент

Таня, ты умница...

ЛОЛ! "Чтобы было ясно, где чей конец"

Что? Хто здесь? Я тута!

а я, тама...

2 Почитай про мою жизнь :( ;

У тебя что, вроде "Свинарка и пастух", тока наоборот?

+ Тебеж вроде бульбу пора из земли вытаскивать... ;)

2(79, 80) Уже все собрали и много съели

а дранники жарили? Люблю я эту гадость...

2 Ну да, немного... с мясом :)

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

2 проверил истину на деле - непьющий дольше проживет. попробовал не пить неделю - мне показалось - прожил год.

а вот у нас есть приговорка... Не пьешь - красота... Выпил - красотищща...

Для 69: Нормально подытожил ;) Для 72: лол Оффтопа много в конце, а так нормально поговорили.

Сегодня столкнулся с грамотными комментариями. 1. Функция. Что делает функция. 2. Внутри функции - // Имя, дата, - что доделано. // Мое имя, дата - что доделано. 2-3 могли в принципе пересекаться. По датам видно. зы Если увижу дату после сегодняшней, налажу переписку.