Уважаемые специалисты, посоветуйте пожалуйста, какой код более читабелен и почему

так:
    ; Создать новый документ
    ClickOnBtn( $oIE, "newDoc"  )
    ; Сохранить изменения
    ClickOnBtn( $oIE, "saveDoc" )

или так:
    
    ClickOnBtn( $oIE, "newDoc"  ) ; Создать новый документ
    ClickOnBtn( $oIE, "saveDoc" ) ; Сохранить изменения

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

(18) Чтобы понять, что делает кнопка, надо прочитать код. Код, а не комментарий.

(19) Плохой код тем более нельзя комментировать.
Поясню:

Вот хороший код с комментарием

с=а+б //сумма а и б

А вот плохой код с комментарием

с=а*б //сумма а и б

Что делает комментарий в плохом коде? Ответ - вредит.

(23) прочитать 1000 срок кода, раскиданный по разным процедурам и функция, это быстрее чем прочесть 1-2 сроки комментария.

(25) 1-2 строки комментария можно прочесть за 10 сек. И это будет ровно 10 сек. впустую потраченного времени.

(24) извините, вы когда физику (или математику) изучали в университете, тоже всегда "от сюда очевидно" раскрывали и проверяли, что из а) получается б) или верили на слово?

+(23) Потому что кнопка делает то, что написано в коде, а не то что написано в комментарии.

(24) Хреновый пример.

Плохой код это... Ну как функции на 7-ке. По 3-4 экрана.

(29) Я упростил для наглядности. Пример не надо воспринимать буквально.

(0) Второй. Код более компактный и комментарии в него не "врываются", находясь рядом, в отдельной зоне.

(26) молодо-зелено...

(0) Вы ещё пишите комментарии? А мы уже программируем! ;)

(32) Сам ты молодо-зелено. Код с трудом читаешь.

(34) я щас читаю код, доставшийся от 3-х поколений разработчиков. вписываю комментарии, в основном такие:

o_O

!?!?!?!?!?

и маты ещё.

Да уж читать "наследство" одно удовольствие))))) Но таки есть коды нормально комментированные... чем вызывает ничего кроме уважения к предыдущим разработчикам

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

обнаружил когда-то вот такие комментарии в коде...
http://savepic.su/4265338.png
интересный феншуй, задротно, однако глаз задерживается на оформлении и проще прослеживать блоки кода тянущиеся непрерывно N скроллов.

чего скажете, господа?)

если вы понимаете код быстрее и лучше, чем 2 строки комментариев, значит ничего сложнее "hello world" не видели

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

(38) что тут сказать... вротмненоги.
(7) а точно )) добавлю:
(0) второй
(1) первый
с (5) согласен

(40) у меня с досовского турбопаскаля привычка переменные обзывать: q, w, qq, qw и т.д.

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

Извращенцы !!!! хотя грешен... сам так пару раз извращался)))))) счас нет...))

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

(43) Ага. Тебе поможет комментарий:
//Эта обработка работает правильно.

Ты его покажешь начальнику и вообще ничего делать не будешь.

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

КоличествоСекундВДне=24*60*60;
ВремяДни=ВремяСекунды/КоличествоСекундВДне;

вместо

ВремяДни=ВремяСекунды/86400; //секунд в дне

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

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

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

верно

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

А мы удивляемся откуда быдлокодеры берутся:) Казалось бы люди на мисте сидят должны пользоваться опытом всего мира, но вот эти их 5 копеек умностей приводят супер проект в такое... :)

+(53)Это в общем о тех кто не пишут комменты.

(52) То, есть в твоем изложении комментирование для себя противоречит комментированию по требованию стандарта?!
Типо для себя с матюками и с сокращением слов в перемешку с анекдотами, а по стандратну - сухой деловой язык?!
:))

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

(48) нам в универе преподы говорили что комментариев в тексте программы должно быть 75%

(52) Заказчики - профаны.
Скажу, чтобы поставить точку в этом вопросе.
Вы, ребята, читаете код, не потому что вам нравится это чтение. А потому что это ваша работа.
Вы читаете код условной обработки, потому что ее надо поправить или доработать. А чтобы обработку поправить или доработать, надо прочитать код обработки.
Еще раз.
Прочитать.
Код.
Не комментарий. Комментарий - мусор. Зачем читать комментарий? Вы прочтете комментарий и не будете читать код?
Тогда вас надо уволить, работнички.

(57) Чтобы им легче было читать, то что вы понапишите. К реальной работе не имеет никакого отношения.

(58) Да. Заказчики - профаны. Были бы спецы - сами бы написали. А подстраховаться всегда хорошо. Коммент может показать в двух фразах общую идею реализации, которую ты без коммента можешь неделю высасывать, собирая идею из процедур и функций.

(58) ты хоть раз разбирал что-нить в типовой конфе? где скачешь из одного общего модуля в другой?

(47) можно сделать глобальную процедуру КоличествоСекундВДне()

(59) Если у тебя такое мнение о комментах, то выскажу мысль, что у тебя нет опыта разработки больших проектов, нет опыта ковыряния в тоннах кода при лимите времени и тд и тп.
С комментами всегда легче. Я их всегда читаю, если чел до меня его оставил, значит это важно и на это он пытается обратить внимание. Как-то так. Точка!

1 вариант легче читать

(61) И что? Как комментарий может избавить тебя от скачек?

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

(65) Если внесено однотипное изменение в 5 процедур, то умный кодер в каждой из 5-ти процедур оставит коммент, где есть эти упоминание на эти 5 процедур. Или грамотно уведомит другого кодера или себя (того, который в будущем) как не заниматься поиском, а сразу подрихтовать эти 5 мест и другие не исследовать.

Так стоп.... уметь читать код- конечно признак профессионализма не спорю... но если надо сделать код максимально компактный например, то стометровые переменные типа КоличествоСекундВГодуСУчетомРабочикДнейЗаВычетомОтпускныхИБольничныхИтакДалееДоПотериВсехВозможныйВариантовименованияПеременной. Конечно будут превращены в банальные a,b,c,d В таком случае уж документация отдельным так сказать описанием должна быть... И каким бы программер не был суперпрофи без описания код программы не прочитать .. иногда никогда...))) Это к тому, что комментарий- это мусор

(68) а, б, с, д - это бредятина. Это программирование сущностями, которые не соотносены с реальными объектами в задачи. Чтобы их соотнести - нужно дополнительное усилие на запоминание такого сопоставление. А посему а, б, с, д применимо на уровне обучения и неприемлимо в коммерческих проектах, ибо демострируют незрелость программиста.

Применение а, б, с, д могу оправдать, если используется общеизвестная формула, или формула, которая расшифрована в комментарии, типа
//тройной интеграл по замкнутому контуру, согласно техзаданию № 00231 от 21.04.2004, стр. 456
...Далее кодинг по формуле...

(69) как быть с языками на латинице? не каждый разраб силён в английском, транслитом писать?

Не согласен. Вам надо написать бортовую программу управления "детским" четырех винтовым вертолетиком, который должен облететь заданный периметр, и в случае разрядки аккумулятора приземлиться на площадке для зарядки или в других ситуациях подать какой либо сигнал на ЦП, вся программа должна поместиться на катрочке памяти размером скажем 512 Мб. (примерно такое применяется в охранных системах больших площадей)...Так вот к чему ет я... в органиченных объемах памяти и при подходе дела  "с комментами и понятными переменными" в указанный объем вместится всего лишь объявление нескольких переменных н еговоря уж о самом коде программы....Поэтому  переменки типа а,б,в,г и т.д. вполне имеют право н аиспользование и никак не связанно с профессионализбмом программера)))

ну мимо кнопок тыкаю иногда ))) уж  ничего не поделаешь с этим)))

(65) newbie :)

(72) "вся программа должна поместиться на катрочке памяти размером скажем 512 Мб"

афигееееееть, да вы, извиняюсь, слишком много кушать

(71) Кодил на Дельфях, для русских заказчиков, комметы - всегда русские с описанием того, что делает процедура/функция/назначение переменной.
Если взялся для буржуев ваять, сломи гордость, забудь русский.
Если пишешь с нуля, то можно придумать и что-то особенное.
Например, каждый коммент начинать спецпоследовательностью (которую ты быстро найдешь глобальным поиском по модуля), или использовать глобальный поиск по признаку коммента.
Или использовать развитые системы разработки, для автогенерации документации. Там это все придумано.
https://ru.wikipedia.org/wiki/%CA%EE%EC%EC%E5%ED%F2%E0%F0%E8%E8_(%EF%F0%EE%E3%F0%E0%EC%EC%E8%F0%EE%E2%E0%ED%E8%E5)

На низком уровне попрограммирить пробовали? там нет ни комментов ни огромных переменных.. там как раз все простенько. По молодости пробовал на ассемблере д асразу в машинных кодах... гемор тот еще)))))) если кто помнит наши ЭВМ типа СМ1420 или ЕС1045 и т.д.))))))

к (74)
тут конфа БП3 на 160 Мб

Ну да много "кушать" конечно же хочется)))) а ведь были времена когда дисковый массив в 80 метров был пределом мечтаний))) и по размерам как холодильник "морозко"))))))

Ну это было  когда земля была еще теплой и по ней ходили динозавры)))

(72) Не согласен, не пиши комменты! Назвай все абсд!

но только когда это оправданно

(76) Для тебя будет открытием, но
http://yandex.ru/yandsearch?text=комментарии%20в%20ассемблере&clid=14585&lr=213

Нет не открытие.... Я вещал о программировании на машинном коде... По ссылке написание с использованием транслятора...
в машинных кодах все выглядит примерно  вот:
010110
010220
110102
010003

То есть никаких тебе ничего ни комменов ни даж переменных
01 = команда move далее номера ячеек и их содержание
11 = команда сложить ячейки результат в ячейку 00
и последнее перенести результат из яч 00 в яч 03... ну и т.д. весь бред исключительно в кодах машины.... зато можно было легко все набить на перфоленточку и хранить в сейфе))))) или на перфокарточку)))) но ет уже другая тема))) не здесь

как думаешь, сколько места займет программа очистки памяти БИОС?

мне один программер дааавно еще написал такую.. не соврать там было примерно 30-40 байт.. на ассемблере исполняемый код под ДОС

Для NikVars http://www.zxpress.ru/article.php?id=5218
Я примерно про это говорил))) тока для промышленных компутеров))) тогда они компутерами и не назывались )) ЭВМ панимаешь ли))))

(85) Можно подумать, он прямо в кодах и писал.

угу... первую сетку тоже так же... по сом порту еще. Извращение то еще)))) ну эт так експерименты были))) тогда еще ссср был)))) но скорость была 9600.. тогда с сом порта больше не выжать)))).. счас сом портик даже и не знаю используется ли где)))

А что ужасного в том, что бы писать "прямо в кодах"?))))

Но по моему эт таки другая темя... от изначальной отвлеклись ооочень сильно))))) Помним? изначально как корректнее оформить комментарии в программном коде?)))))))

(89) Читать/отлаживать неудобно. На моей памяти вручную кодировали по ассемблерному листингу.

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

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

)))))) ну может и не самая важная, но хотелось бы , что бы все было близко к какому то идеалу что ли))

(92) И скальпель, чтобы прорезать недостающую дырочку, и мусор из УПДК, чтобы забить лишние дырочки. И читали карты на просвет! :)

ностальжи?????

(86) Хочешь оправдать свое современное представление о комментах своим тяжелым машиннокодовым детством?!
Или перескакивая на другие темы показываешь свою эрудицию?!
Или ты тут демонстрируешь, что не способен впитывать новое, так как в ИТ - все новое - это забытое старое?!
Все что ты тут привел в пример - умерло. Можешь продолжать раскапывать могилы и пытаться реанимировать трупики. Не изменишься сам - умрешь сам (в профессиональном плане в области ИТ).

(94) перфекционистам вообще низзя с 1С работать. Ибо будут несчастные в вечной депрессии))

Нет я ничего не оправдываю. Про Коды вообще было не к комментам написано...)))) А на тему использования переменных типа a,b,c,d и т.д.)))

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

(100) конечно же, я стараюсь писать красиво (в моем понимании), лесенкой, с комментариями, но такое внимание комментариям не уделяю, пишу то справа строки, то сверху, где как удобно, в элементарных блоках не пишу вообще или пишу в целом : здесь будем делать то и это)
Но все же тема больше из серии, с какой стороны есть яйцо  - с тупого конца или с острого) Я просто за то, что дозы перфекционизма должны быть разумные)

А кто как относиться к такому коду, в одну строку, если один оператор? ex.

Если ВсеПропало тогда Возврат; КонецЕсли;

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

Матом главное не пишите.

)))) матом?)))) а это идея)))

Язык программирования на матном языке))))

(0) Вот так:
    ; Создаем новый документ и сохраняем его
    ClickOnBtn( $oIE, "newDoc"  )
    ClickOnBtn( $oIE, "saveDoc" )

(106) Один оператор с множественным смыслов в зависимости от контекста?
Не, не дошли технологи еще до понимания и трансляции в машинный код такого языка

(108) отчего же, взять например =
оператор зависит от контекста.

в 1с

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

+(111) Соответственно, чем богаче внутренний мир (больше состояний машины) тем меньшим алфавитом на ленте можно пользоваться.

(112) тонко вы задвинули про богатый внутренний мир в обсуждении про матерный ЯП :)

(113) да, начиналось все так невинно)) а по факту, все уже есть - просто бери и пиши) вместо "Документ.Ссылка" можно использовать "мать его так"))

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

(115) Ну да. Если пишут студенты для студентов...

(109) Если просто заменить названия операторов на мат, ничего путного не получиться. В мате важна именно смысловая нагрузка.
Сомневаюсь, что 1с сможет въехать в  
Найти скока ща буржуйские бабки стоят
Справочники.Валюты.НайтиПоНаименованию("USD")

Да... жаль интонацию нельзя передать при написании... так бы один единственный оператор мог бы выполнять до 10 и более функций. Помните как в мультике про морячка Рому? использовановсего лишь одно слово Рома.. а сколько разных смыслов мы услышали))))))))

(118) https://ru.wikipedia.org/wiki/Ook!

скопировать с восклицательным знаком в конце

Если блоками, то сверху, если по 1 строчке то справа

О! супер))