Старший разработчик в нашем магазине настаивает на том, что всякий раз, когда код изменяется, ответственный программист должен добавить встроенный комментарий с указанием того, что он сделал. Эти комментарии обычно выглядят как// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

Мы используем TFS для контроля ревизий, и мне кажется, что такого рода комментарии гораздо более уместны, чем заметки о регистрации, а не встроенный шум. TFS даже позволяет связать регистрацию с одной или несколькими ошибками. Некоторые из наших старых, часто изменяемых файлов классов выглядят так, как будто их соотношение комментариев к LOC приближается к 1: 1. На мой взгляд, эти комментарии усложняют чтение кода и добавляют ноль значения.

Это стандартная (или, по крайней мере, распространенная) практика в других магазинах?

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

Тем не менее , я все еще часто делаю что-то подобное для определенных типов правок.

Случай 1 - Задачи

Если вы используете IDE, такую ​​как Eclipse, Netbeans, Visual Studio (или у вас есть какой-либо способ выполнения текстового поиска в вашей кодовой базе с помощью чего-либо еще), возможно, ваша команда использует некоторые конкретные «теги комментариев» или «теги задач». В этом случае это может быть полезно.

Время от времени при просмотре кода я добавляю что-то вроде следующего:

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

или:

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

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

Случай 2 - патчи сторонних разработчиков

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

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

Случай 3 - неочевидные исправления

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

В продукте, над которым я работаю в данный момент, у нас иногда (определенно нетипично) есть комментарий вроде:

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

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

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

Это только в: реальный пример из жизни

В некоторых случаях это лучше, чем ничего :)

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

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

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

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

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

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

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

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

Как правило, это не требуется, если ваши SCM и IDE позволяют вам использовать функцию «show annotation» (в любом случае это называется в Eclipse), вы можете легко увидеть, какие коммиты изменили фрагмент кода, и комментарии коммитов должны указать, кто и почему.

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

Очевидно, что любые такие комментарии почти гарантированно будут неправильными с течением времени; если вы редактируете строку дважды, добавляете ли вы два комментария? Куда они идут? Так что лучше всего полагаться на свои инструменты.

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

Вы должны понять, почему он не может положиться на это. Это старые привычки? Неудачный опыт работы с системой SCM? Формат презентации, который не работает для него? Возможно, он даже не знает о таких инструментах, как «git blame» и представление временной шкалы Perforce (что, по сути, показывает это, хотя может и не показывать, какая проблема вызвала изменение).

Без понимания его причины требования, вы не сможете убедить его.

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

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

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

Комментарий с номером дефекта дает мне место для поиска источника кода.

Так что, да, система SCM делает много, но не все. Относитесь к ним так же, как к любым другим комментариям, и добавляйте их везде, где вносятся существенные изменения. Разработчик, глядя на ваш код 5+ лет, как вы будете благодарны.

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

Не то, чтобы я мог сказать.

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