Альтернативы комментированию кода для исторических целей

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

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

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

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

Единственные варианты, о которых я мог подумать, были:

Wiki: просто вставьте его где-нибудь в вики. Недостатком этого является то, что он будет смешан с другим вики-содержимым, не связанным с кодом, что может затруднить поиск на нем.
Индекс всех версий VCS. Это в значительной степени теоретический для меня, но существуют ли системы, которые делают кодовую базу и всю ее историю доступной для поиска?

Кто-нибудь знает или использует какие-либо альтернативы? Оба моих варианта звучат как больше работы, чем на самом деле, но это может быть искажено моими рассуждениями о том, что прокомментированный код бесполезен в любом случае. Мне бы очень хотелось, чтобы я пошел "Эй, если у вас нет времени исправить это сейчас, это не так важно, чтобы оставаться в кодовой базе в любом случае" (но я буду, если нет жизнеспособных альтернатив).

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

Ответ 1

Ветвление может быть полезно здесь. Одной из моделей использования SCM является создание ветки для каждой функции. Это популярно, когда слияние веток безболезненно - легкость, которую не могут обеспечить все SCM...: -)

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

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

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

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

Что касается поиска, некоторые SCM имеют интерфейс поиска. Например, SVN имеет SVNSearch - http://sourceforge.net/projects/svn-search/. Существует также svnquery, который может искать историю, а также голову.

Ответ 2

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

Я бы сохранил в системе контрольной версии, но я бы сохранил ее в отдельной папке, что-то вроде removed-code-to-review-later. Тогда я удалю его, когда я его просмотрю.

Ответ 3

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

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

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

Ответ 4

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

Ответ 5

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

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

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

Существуют системы контроля версий, которые очень хороши при создании и объединении веток. Mercurial, git и т.д. Могли бы все это сделать. Даже если вы не используете один из них в качестве основного VCS, вам нечего мешать вашему коллеге создавать локальный репозиторий, чтобы сохранить свои эксперименты.

Ответ 6

В некоторых сценариях рекомендуется документировать решения некоторых сложных/уникальных проблем для справочных целей. Я не думаю, что это должно быть в коде. IMHO Я думаю, что Wiki какой-то вариант - лучший вариант.

Если вы еще не использовали код за последние 2 года, вы его когда-нибудь будете использовать, и если вы все равно будете использовать код, которому 2 года? Если вам когда-нибудь понадобится добавить эту логику снова в код, возможно, лучше написать ее с нуля, поскольку, скорее всего, в течение этого периода все изменилось бы, вы бы многому научились, дополнительные ресурсы были бы доступны вам и т.д.

Ответ 7

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

< >

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

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