Являются ли устаревшие комментарии городским мифом?

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

Мне просто повезло, с кем я работаю? Являются ли определенные отрасли более склонными к этой проблеме, чем другие? У вас есть конкретные примеры последних устаревших комментариев, которые вы видели? Или устаревшие комментарии являются скорее теоретической проблемой, чем реальной?

Постоянно

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

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

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

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

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

Конкретные примеры:

• Комментарии, описывающие улучшение производительности для конкретной методологии, например, избегание копирования в памяти. Большое дело, когда топовый компьютер в Pentium 2 с мегабайтами оперативной памяти, но вряд ли проблема сейчас.

• Todos

• Блоки скопированного кода, включая комментарии. Комментарий, возможно, имел смысл в своем первоначальном расположении, но вряд ли имеет смысл здесь

• Блоки комментариев поверх закомментированного кода (Кто знает, сколько лет там было).

Во всем этом вы видите тенденцию просто не поддерживать комментарии и код на том же уровне, что и программное обеспечение. В этом не помогают IDE и базовые привычки разработчиков, мой глаз обучен тому, как быстро обойти их. Я думаю, что устаревшие комментарии относительно дешевы, чтобы их избегать в «зеленых» и активных проектах. Если вы можете поддерживать соотношение код / ​​комментарий на высоком уровне, не составляет большого труда поддерживать их в актуальном состоянии. Немного сложнее оправдать поиск этих вещей, когда вы потратили х часов на исправление ошибки в производственной системе.

«комментарии имеют тенденцию устаревать».

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

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

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

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

Недавнее исследование Roehm et al. 2012 год отмечает следующее:

21 участник [из 28] сообщил, что они получают основную информацию из исходного кода и встроенных комментариев, тогда как только четверо заявили, что документация является их основным источником информации.

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

_{Roehm, T., Tiarks, R., Koschke, R. & Maalej, W. (2012, июнь). Как профессиональные разработчики понимают программное обеспечение? В материалах Международной конференции 2012 года по разработке программного обеспечения (с. 255-265). IEEE Press.}

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

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

Комментарии похожи на тесты, они очень хороши, когда они обновлены, но могут усложнить понимание кода, если его нет.

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

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

Устаревшие комментарии часто появляются в JavaDoc:

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

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

Я имею дело с устаревшими комментариями время от времени. Это, конечно, не городской миф. Люди упоминают об этом в списках наихудших практик не потому, что это бьет вас очень часто, а потому, что когда это происходит, это обычно стоит вам много времени и усилий.

В нашей кодовой базе большинство устаревших комментариев вызвано использованием (анти) шаблона описания поведения метода рядом с его вызовом, а не рядом с объявлением метода. Это происходит, когда кто-то извлекает длинный кусок кода в метод, который в данный момент вызывается только один раз, а затем комментирует вызов метода. Таким образом, вы получите что-то вроде этого:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

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

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

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

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

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

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

//TODO: In 15 years AND NO SOONER... actually implement this method.

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

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

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

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

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