Вы приводите пример мусорного комментария.
Гораздо лучше делать так:
// Создадим наш главный рабочий объект
var someEntity = new Processor();
То, что это объект очевидно, но чтобы понять, что этот объект «самый главный» для данного фрагмента кода, если комментария нет, придется сначала прочитать код. А если есть — то картинка в голове возникает сразу.
Вы приводите пример мусорного комментария.
Гораздо лучше делать так:
// Создадим наш главный рабочий объект
var someEntity = new Processor();
То, что это объект очевидно, но чтобы понять, что этот объект «самый главный» для данного фрагмента кода, если комментария нет, придется сначала прочитать код. А если есть — то картинка в голове возникает сразу.
На самом деле, есть еще такая беда, как необходимость формирования стека при вызове функции (на низком уровне не так все просто работает), поэтому является ли замена if-а на вызов функции выигрышем или проигрышем — это еще большой вопрос.
Нет, не издеваюсь. Прошу прощения, если так выглядит.
Пример-то, конечно, относительно абстрактный, но мы разбираем необходимость комментариев именно на нём.
Вы пытаетесь мне доказать, что код должен быть самокомментирующимся (с чем я согласен!), но я утверждаю, что этого самокомментирования не достаточно, т.к. читабельность этого кода можно значительно повысить за счёт полноценных комментариев на человеческом языке.
Ваше замечание, к сожалению, не по существу. В данном случае код совершенно абстрактный и подразумевается, что onClick — это некий обработчик нажатия на некую кнопку, т.е., фактически, имеется в виду то, что вы написали в своем первом примере.
Дело в том, что в программах далеко не все алгоритмы относятся к стандартным (типа квадратных корней), а значит, читатель кода (особенно, если он не автор) во многих случая окажется неподготовленным. Комментарии на естественном языке гораздо читабельнее программного кода, поэтому чтение и понимание хорошо откомментированного кода происходит гораздо быстрее, чем (любого!) неоткомментированного.
Полностью не согласен.
Комментировать логику надо всегда и достаточно подробно, и при изменении логики надо менять комментарии. Естественно, писать что-то типа: a = b; // скопируем параметр b в a
это тупо и является примером мусорного комментирования.
Комментарии должны отображать глобальный смысл происходящего:
Если один метод работает с несколькими юз-кейсами, значит, это должно быть отражено в коде в виде условных переходов. И, судя по всему, разница между этими юз-кейсами «зашита» где-то в середине кода и хрен сразу разберешься в режимах работы.
А это означает, что ошибка «номера один» в том, что он не умеет наглядно показать в своём методе, все его режимы работы. А делается это довольно просто: все параметры, влияющие на режим работы, необходимо выносить в начало метода и там их подробно комментировать, тогда «второй» сможет легко и непринуждённо, прочитав список параметров оценить все юз-кейсы без необходимости лезть в интерфейс.
Вот именно.
По моему опыту, непосредственно написание кода составляет очень малую часть работы программиста и увеличение объема кода на 20% почти не скажется на общем времени выполнения, а основное время уходит на продумывание общей структуры кода, алгоритма работы и дебаг. Написать короткую функцию без логики — 20 секунд. Чем сложнее логика, тем больше удельного времени приходится на каждую строчку кода — в десятки-сотни-тысячи раз больше.
Смысл как раз в том, что про существование этих методов помнить вообще не надо, потому что они, во-первых, не выполняют алгоритмически важной функции (в основном выполняют структурную функцию), во-вторых, легко находятся при необходимости через привязку к кнопочкам (обратный поиск — от ядра функционала к кнопочкам — нужен гораздо реже, чем от кнопочек к ядру).
Кстати, хочу заметить, что совершенно стандартная проблема программиста «формочек» в том, что он пишет методы, которые тянут данные непосредственно из элементов формы, типа:
function onClick()
{
testFormInput(textField1.text, button2.state);
}
function testFormInput(text, state)
{
...
if(text == 'Hello!' && state == 'disabled') { ... }
...
}
в результате: код хардкорно привязан к элементам интерфейса, и, не дай бог, надо поменять структуру формы. Точки входа данных всегда необходимо минимизировать по количеству и строго систематизировать, потому что именно входные данные — это то, что вносит хаос в выполнение нашей идеальной программы.
Лично я полностью поддерживаю «второго» и тоже стараюсь использовать именно такой подход.
С другой стороны, ему, видимо (если я правильно всё понял), не хватает навыка непосредственно перед правкой проверять, где вызывается метод, который он исправляет, чтобы учесть все варианты.
Эти два подхода могут быть объединены за счёт правильной параметризации обработчика. Т.е. обработчик может быть один и универсальный, но в нём все юзе-кейсы должны быть отражены в виде входных параметров. Это либо непосредственно параметры методов:
Т.е. код должен быть организован так, чтобы программисту вообще не требовалось выяснять, в из каких мест данный метод вызывается, чтобы найти и исправить баг (конечно, кроме случаев, когда баг заключается именно в некорректности входных параметров).
Однако, гораздо нагляднее, я считаю, для разных кнопочек делать разные обработчики, которые внутри себя уже могут вызывать один и тот же метод для реализации универсальной части функционала.
Лично для меня изменение синтаксиса языка (например, PHP) всегда упиралось в то, что среды разработки поддерживают только стандарт, и добавление в них соответствующих изменений может обернуться отдельным весёлым и сказочным геморройчиком.
Гораздо лучше делать так:
// Создадим наш главный рабочий объект
var someEntity = new Processor();
То, что это объект очевидно, но чтобы понять, что этот объект «самый главный» для данного фрагмента кода, если комментария нет, придется сначала прочитать код. А если есть — то картинка в голове возникает сразу.
Гораздо лучше делать так:
То, что это объект очевидно, но чтобы понять, что этот объект «самый главный» для данного фрагмента кода, если комментария нет, придется сначала прочитать код. А если есть — то картинка в голове возникает сразу.
Пример-то, конечно, относительно абстрактный, но мы разбираем необходимость комментариев именно на нём.
Вы пытаетесь мне доказать, что код должен быть самокомментирующимся (с чем я согласен!), но я утверждаю, что этого самокомментирования не достаточно, т.к. читабельность этого кода можно значительно повысить за счёт полноценных комментариев на человеческом языке.
Речь вообще шла о том, какие должны быть комментарии в коде)
За такой бардак своему подчинённому шею бы намылил)))
Выделять дискриминант в отдельный объект — это жесть))
Гораздо лучше так:
Соответственно, в общем случае правильнее было бы так:
А внутри уже то, что я писал выше.
Комментировать логику надо всегда и достаточно подробно, и при изменении логики надо менять комментарии. Естественно, писать что-то типа:
a = b; // скопируем параметр b в aэто тупо и является примером мусорного комментирования.
Комментарии должны отображать глобальный смысл происходящего:
Комментарии — это описание работы алгоритма на человеческом языке.
А это означает, что ошибка «номера один» в том, что он не умеет наглядно показать в своём методе, все его режимы работы. А делается это довольно просто: все параметры, влияющие на режим работы, необходимо выносить в начало метода и там их подробно комментировать, тогда «второй» сможет легко и непринуждённо, прочитав список параметров оценить все юз-кейсы без необходимости лезть в интерфейс.
По моему опыту, непосредственно написание кода составляет очень малую часть работы программиста и увеличение объема кода на 20% почти не скажется на общем времени выполнения, а основное время уходит на продумывание общей структуры кода, алгоритма работы и дебаг. Написать короткую функцию без логики — 20 секунд. Чем сложнее логика, тем больше удельного времени приходится на каждую строчку кода — в десятки-сотни-тысячи раз больше.
вместо
в результате: код хардкорно привязан к элементам интерфейса, и, не дай бог, надо поменять структуру формы. Точки входа данных всегда необходимо минимизировать по количеству и строго систематизировать, потому что именно входные данные — это то, что вносит хаос в выполнение нашей идеальной программы.
С другой стороны, ему, видимо (если я правильно всё понял), не хватает навыка непосредственно перед правкой проверять, где вызывается метод, который он исправляет, чтобы учесть все варианты.
Эти два подхода могут быть объединены за счёт правильной параметризации обработчика. Т.е. обработчик может быть один и универсальный, но в нём все юзе-кейсы должны быть отражены в виде входных параметров. Это либо непосредственно параметры методов:
либо параметры вычисляемые в начале тела метода:
Т.е. код должен быть организован так, чтобы программисту вообще не требовалось выяснять, в из каких мест данный метод вызывается, чтобы найти и исправить баг (конечно, кроме случаев, когда баг заключается именно в некорректности входных параметров).
Однако, гораздо нагляднее, я считаю, для разных кнопочек делать разные обработчики, которые внутри себя уже могут вызывать один и тот же метод для реализации универсальной части функционала.