Хорошо ли комментировать код, который удаляется? Например:
// Code to do {task} was removed by Ajahn on 10/10/08 because {reason}.
Кто-то из моей группы разработчиков во время экспертной оценки сделал заметку о том, что мы должны прокомментировать строки кода, которые нужно удалить. Я думал, что это было страшное предложение, так как оно загромождает код бесполезными комментариями. Кто из нас прав?
Как правило, удаляемый код не должен комментировать, именно потому, что он загромождает кодовую базу (и, почему бы прокомментировать что-то, что не существует?).
Ваша система отслеживания дефектов или инструменты управления источником управления находятся там, где такие комментарии принадлежат.
Есть некоторые (редкие) ситуации, когда комментирование кода (а не удаление) является хорошей идеей. Вот один.
У меня была строка кода, которая казалась хорошей и необходимой. Позже я понял, что это ненужно и вредно. Вместо того, чтобы удалять строку, я прокомментировал ее, добавив еще один комментарий: "Нижеследующая строка неверна по такой-то причине". Почему?
Потому что я уверен, что следующий читатель кода сначала подумает, что эта строка не является ошибкой и попытается добавить ее обратно. (Даже если читатель будет мне через два года.) Я не ожидаю, что он сначала обратится к источнику контроля. Мне нужно добавить комментарий, чтобы предупредить его об этой сложной ситуации; и неправильная линия, и причина, по которой это неправильно, оказалось лучшим способом сделать это.
Я согласен, что не рекомендуется оставлять код в комментариях.
Историю кода следует просматривать через систему управления версиями, где можно найти старый код, а также причину, по которой он был удален.
Вы всегда должны удалять код.
Что касается возможности видеть старый/удаленный код, то какой контроль над версиями.
Зависит от причины удаления.
Я думаю о комментариях как о подсказках для людей, поддерживающих код в будущем, если информация о том, что код была там, но была удалена, может быть полезной для кого-то, поддерживающего код (возможно, как знак "не делай этого" ) то он должен быть там.
В противном случае добавление подробных комментариев с именами и датами при каждом изменении кода просто сделает все это нечитаемым.
Я думаю, что это бесполезно и сделать код менее читаемым. Подумайте, как это будет после некоторых месяцев...
// removed because of this and that
/*
removed this stuff because my left leg...
*/
doSomething();
// this piece of has been removed, we don't need it...
Вы потратите полчаса, чтобы узнать, что происходит
Вопрос в том, почему вы удаляете код?
Неужели это бесполезно? Было ли ошибкой поставить его там в первую очередь?
С моей точки зрения никаких комментариев не требуется.
Это полезно при отладке, но нет причин проверять код таким образом. Вся цель управления версиями - восстанавливать старые версии без загромождения кода кодом с комментариями.
Я бы предположил, что это хорошая практика, чтобы комментировать код, который был удален, но не в самом коде.
Чтобы прояснить эту позицию, вы должны использовать систему управления исходным кодом (SCCS), которая позволяет получить какую-либо форму комментария. Здесь вы должны поместить комментарии о том, почему код был удален. SCCS предоставит полную контекстуальную историю того, что произошло с кодом, включая то, что было удалено. Добавив комментарии для регистрации, вы также уточняете историю.
Добавление комментариев в код непосредственно приводит к беспорядку.
Недавний консенсус (из других обсуждений здесь) заключается в том, что код следует просто удалить.
Я лично буду комментировать код и пометить его датой или причиной. Если он старый/устаревший, и я просматриваю файл, то я его вынимаю. Контроль версий упрощает работу, но не так просто, как раскомментирование...
Похоже, вы пытаетесь обойти версию вашего кода. Теоретически это звучит как отличная идея, но на практике это может очень запутать очень быстро.
Я очень рекомендую комментировать код для отладки или запуска других тестов, но после того, как окончательное решение было принято, полностью удалите его из файла!
Получите хорошую систему управления версиями на месте, и я думаю, вы обнаружите, что практика комментирования изменений бесполезна.
Никто здесь не написал много о том, почему вы не должны оставлять прокомментированный код, кроме того, что он выглядит грязным. Я думаю, что самая большая причина в том, что код, скорее всего, перестанет работать. Никто не компилирует его. Никто не работает через модульные тесты. Когда люди реорганизуют остальную часть кода, они не рефакторизуют его. Так скоро, это станет бесполезным. Или хуже, чем бесполезно - кто-то может раскомментировать его, слепо веря, что он работает.
Есть моменты, когда я буду комментировать код, если мы все еще делаем тяжелый дизайн/разработку в проекте. На этом этапе я обычно тестирую несколько разных конструкций, ища правильный подход. И иногда правильный подход - это тот, который я уже делал ранее. Так что приятно, если этот код не потерян в глубинах управления источником. Но как только дизайн будет улажен, я избавлюсь от старого кода.
В целом я склоняюсь к комментариям очень редко. Я считаю, что хороший код должен быть легко читаемым без особого комментария.
Я также версия моего кода. Полагаю, я мог бы сделать разницу за последние двадцать проверок, чтобы увидеть, изменилась ли какая-то конкретная строка по определенной причине. Но это было бы огромной тратой времени для большинства изменений.
Итак, я очень стараюсь комментировать мой код. Если какой-либо код удаляется по довольно очевидной причине, я не буду комментировать его удаление. Но если фрагмент кода удаляется по тонкой причине (например, он выполняет функцию, которая теперь обрабатывается другим потоком), я буду комментировать или удалить код и добавить комментарий к баннеру, почему:
// this is now handled by the heartbeat thread
// m_data.resort(m_ascending);
Или:
// don't re-sort here, as it is now handled by the heartbeat thread
Только в прошлом месяце я столкнулся с частью кода, который я изменил год назад, чтобы исправить конкретную проблему, но не добавил комментарий, объясняющий почему. Вот исходный код:
cutoff = m_previous_cutofftime;
И вот код, который первоначально был исправлен для использования правильного времени отсечки при возобновлении прерванного состояния:
cutoff = (!ok_during) ? m_previous_cutofftime : 0;
Конечно, возникла еще одна не связанная с этим проблема, которая коснулась той же строки кода, в этом случае вернув ее обратно в исходное состояние. Таким образом, новая проблема теперь была исправлена, но старая проблема внезапно стала переродиться. D'о!
Итак, теперь зарегистрированный код выглядит следующим образом:
// this works for overlong events but not resuming
// cutoff = m_previous_cutofftime;
// this works for resuming but not overlong events
// cutoff = (!ok_during) ? m_previous_cutofftime : 0;
// this works for both
cutoff = (!resuming || !ok_during) ? m_previous_cutofftime : 0;
Конечно, YMMV.
Как одинокий несогласный голос, я скажу, что есть место для комментирования кода в особых обстоятельствах. Иногда у вас будут данные, которые продолжают существовать, которые выполнялись через этот старый код, и самая ясная вещь - оставить этот старый код с источником. В таком случае я, вероятно, оставил бы небольшую заметку, указывающую, почему старый код просто закомментирован. Любые программисты, идущие дальше, смогут понять все еще существующие данные, не пытаясь психически обнаружить необходимость проверки старых версий.
Обычно, я считаю, что код с комментариями совершенно одиозный, и я часто удаляю его, когда сталкиваюсь с ним.
Если вы удаляете код. Вы не должны комментировать, что вы его удалили. Это целая цель управления версиями (вы используете источник управления? Правильно?), И, как вы заявляете, комментарий просто загромождает код.
Я согласен, что это страшное предложение. Вот почему у вас есть Source Control, который имеет ревизии. Если вам нужно вернуться и посмотреть, что было изменено между двумя версиями, выполните различие между двумя версиями.
Мне не нравится видеть код, который загроможден скомментированным кодом. Удалите код и напишите сообщение фиксации, в котором говорится, почему он был удален. Вы используете источник управления, не так ли?
Не мутируйте активный код мертвым кодом.
Я добавлю свой голос к консенсусу: поместите комментарии о том, почему код был удален в репозитории управления версиями, а не в коде.
Это один из этих "сломанных" оконных мышц, таких как подсказки/предупреждения компилятора, оставленные без адреса. это повредит вам однажды, и это способствует неряшливости в команде.
Комментарии в контроле версий могут отслеживать, почему/почему этот код был удален - если разработчик не оставил заметки, отследите их и запустите.
Небольшой анекдот, для удовольствия: несколько лет назад я был в компании, ничего не зная о контроле версий исходного кода (позже они получили такой инструмент...).
Таким образом, в наших источниках у них было правило: "когда вы вносите изменения, отключите старый код с помощью макросов препроцессора":
#ifdef OLD /* PL - 11/10/1989 */
void Buggy()
{
// ...
}
#else
void Good()
{
// ...
}
#end
Не нужно говорить, наши источники быстро стали нечитаемыми! Это был кошмар для поддержания...
Поэтому я добавил к SciTE способность перепрыгивать между вложенными #ifdef/#else/#end и т.д. Он может быть полезен в более обычных случаях.
Позже я написал макрос Visual Studio, чтобы с радостью избавиться от старого кода, как только мы получили наш VCS!
Теперь, как и buti-oxa, когда-то я почувствовал необходимость указать, почему я удалил какой-то код. По той же причине или потому, что я удаляю старый код, который, как мне кажется, больше не нужен, но я не уверен (наследие, наследие...). Очевидно, что не во всех случаях!
На самом деле я не оставляю такой комментарий, но я могу понять необходимость.
В худшем случае, я хотел бы прокомментировать одну версию и удалить все в следующей версии...
В моей текущей работе, для важных локальных изменений, мы оставляем старый код, но можем активировать его по свойствам, в случае чрезвычайной ситуации. После тестирования на некоторое время в процессе производства мы в конечном итоге удалим старый код.
Конечно, комментарии VCS - лучший вариант, но когда изменение - это несколько строк в большом файле с другими изменениями, ссылка на небольшое удаление может быть трудной...
Если вы находитесь в середине серьезных изменений и вам необходимо исправить существующую функциональность, комментируя будущий код, это разумная вещь, если вы заметите, что это будущая функциональность, по крайней мере, до тех пор, пока у нас не появится фьючерс дружественные системы управления источниками.
Я также считаю это страшным предложением:)
Вы должны использовать исходный контроль, и если вы удалите какой-либо код, вы можете добавить комментарий при фиксации. Таким образом, вы все еще имеете историю кода, если хотите...
Я прошу прокомментировать код, потому что вы никогда не знаете, когда вам придется отказаться от древнего кода, и, может быть, старый код поможет другим людям понять его, если тогда было проще.
Я согласен с вами, Андрей; ИМО - вот почему вы используете контроль версий. С хорошими комментариями checkin/commit и инструментом diff вы всегда можете узнать, почему строки были удалены.
Если вы используете какую-либо форму Source Control, этот подход несколько избыточен (пока используются дескриптивные сообщения журнала)
Существует общая практика "чистого кода", в которой говорится, что никогда не следует удалять код с комментариями, поскольку он засоряется, и поскольку ваш CVS/SVN все равно будет его архивировать.
Хотя я согласен с этим принципом, я не думаю, что это приемлемый подход для всех ситуаций развития. По моему опыту, очень немногие люди отслеживают все изменения в коде и каждую регистрацию. в результате, если нет кода с комментариями, они, возможно, никогда не осознают, что он когда-либо существовал.
Комментируя такой код, можно было бы дать общее предупреждение о его удалении, но, конечно же, нет никаких гарантий того, что заинтересованные стороны когда-либо увидят это предупреждение (хотя, если они часто работают с этим файлом, они увидят это).
Я лично считаю, что правильный подход заключается в том, чтобы преобразовать этот код в другой частный метод, а затем связаться с соответствующими заинтересованными сторонами и уведомить их о ожидающем удалении, прежде чем фактически избавиться от этой функции.
Где я нахожусь, мы комментируем старый код для одного цикла выпуска и затем удаляем комментарии после этого. (Это дает нам возможность быстрого исправления, если какой-то новый код проблематичен и его нужно заменить старым кодом.)
Почти во всех случаях старый код должен, конечно, удаляться и отслеживаться в вашем RCS.
Как и все, однако, я думаю, что сделать выражение "Все удаленные коды ВСЕГДА удаляются" - это неправильный подход.
Старый код, возможно, захочет остаться в мириаде причин. Основная причина оставить код в том, когда вы хотите, чтобы любой разработчик, который работает в этом разделе кода в будущем, увидит старый код.
Полагаясь на отслеживание источников, очевидно, это не дает.
Итак, я верю, что правильный ответ:
-Удалить старый код, если не оставить его, предоставляет важную информацию, необходимую для следующего разработчика в коде. То есть, удалите его в 99% случаев, но не делайте драконовское правило, которое избавит вас от возможности предоставить столь необходимую документацию следующему разработчику, если того потребуют обстоятельства.