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

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

1. Я закомментирую весь код, который, я подозреваю, мне придется изменить. Я рассматриваю закомментированный код как своего рода TODO-список.
2. Я постепенно просматриваю закомментированный код и раскомментированные части этого кода или копирую и вставляю их в другое место, а затем редактирую их по мере необходимости или переписываю части этого кода с нуля, просматривая закомментированный код для справки. Всякий раз, когда я думаю, что я закончил с частью закомментированного кода, я удаляю его.
3. Я продолжаю это, пока не вижу больше закомментированного кода.

Я должен отметить, что я в основном делаю это на личном проекте, который я разрабатываю один.

Однако мне сказали, что я должен прекратить это делать. Мне сказали, что вместо этого я должен начать использовать git, обращаясь к старым коммитам, чтобы увидеть старый код, вместо того, чтобы оставлять закомментированный код. Мне сказали:

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

Могу ли я спросить, каковы эти недостатки того, что я делаю, что я не вижу сейчас?

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

Для полноты, я чувствую, что должен добавить, что человек, которого я цитирую, является опытным разработчиком и фанатом «Чистого кода» дяди Боба - и дядя Боб действительно критиковал комментирование кода в его книге.

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

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

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

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

Могу ли я спросить, каковы эти недостатки того, что я делаю, что я не вижу сейчас?

Можно утверждать, что нет, если вы работаете в одиночку, не используете контроль версий и чувствуете, что это нормально.

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

Если вы используете контроль версий, и у вас есть множество комментариев в качестве «списка задач», и вы исправляете некоторые и удаляете комментарий, затем повторяете, затем повторяете и т. Д., Тогда у вас есть код «в процессе» и комментарии сохраняются в вашей истории изменений. Это не будет проблемой, если вам никогда не придется откатываться на другой коммит или даже «вишню» позже (например, здесь вы берете конкретные коммиты и перетаскиваете их в другую используемую ветку). Но в противном случае это может быть проблемой.

Возможно, это можно сравнить с «моментальными снимками» программного обеспечения на жестких дисках, как это было в Windows («Восстановление»). Если он делает снимок с вирусом, вы убиваете вирус, но затем вам нужно откатиться, и вы можете вернуться к точке, где вирус снова присутствует.

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

Кроме того, при работе над большим проектом вы склонны к совместной работе, частым коммитам и подталкиванию, поэтому возможно, что их ветвь, над которой они работают, будет иметь ваш список TODO, если они объединят вашу ветку с их. Тогда ваш список TODO - дело каждого: D

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

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

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

Похоже, ваш рецензент немного догматичен. Я не уверен, что ругаться за комментирование кода - это ПК ;-), или даже полезно ;-)

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

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

Но наличие списка TODO внутри кода (будь то маркированные списки или старый код) - вполне разумно, на мой взгляд. Но вы можете немного пересмотреть вопрос о том, как вы это делаете. Во-первых, я предлагаю подумать о том, чтобы кто-то еще читал ваш код. Чтобы кто-то еще мог быть вами, через год после того, как вы бросили и присоединились к проекту. Или это может быть кто-то еще полностью. ПРОСТО столкновение с закомментированным кодом немного сбивает с толку. Может быть что-то вроде:

/*
 * Need this sort of functionality added back before too long:
 * .... OLD CODE HERE
 */

Лично я больше склоняюсь к чему-то вроде этого:

 * TODO:
 *      @todo   Possible get rid of intermediate LRUCache_ object.
 *
 *      @todo   Find some reasonable/simple way to get
 *              LRUCache<PHRShortcutSpec, PHRShortcutSpec, PHRShortcutSpecNoAuthCacheTraits_>   sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
 *              Working with ONE T argument
 *              Add(elt2cache).
 ...

и я не стесняюсь добавлять «фрагменты кода» из старого кода как полезные.

Использовать git сложно (к сожалению). Вам понадобится некоторое время, чтобы научиться, и может показаться, что это не часть того, чего вы пытаетесь достичь. Но если вы собираетесь программировать с пользой, вам нужно научиться делать это как часть команды и общаться с командой, и git - это именно то, как это делается в наши дни. И как только вы освоите его, вы найдете ОЧЕНЬ полезный инструмент / опору, облегчающий разработку программного обеспечения.

Удачи!

Есть много причин, чтобы закомментировать код: -

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

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

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

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

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

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

Это плохо, и ты должен остановиться .

Причина кроется в попытке сделать большое количество рефакторинга за один раз.

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

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

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

Сделайте шаги ребенка и проверьте после каждого:

• извлечь интерфейс
• написать тест
• рефакторинг функции

Не помечайте большие куски кода как «ваши», комментируя их, и забирайте их для самостоятельной работы до тех пор, пока они не будут завершены или вы не потерпите неудачу.

Если вам нужно отслеживать, что нужно сделать, используйте доску задач, например, scrum или trello