Я обычно считаю такие комментарии плохой практикой, и я думаю, что такая информация принадлежит журналам фиксации 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: рецензентом, датой, идентификатором ошибки.
Сначала я подумал о списании, но заметил, что идентификаторы ошибок не только не соответствуют условию нашего текущего средства отслеживания проблем, но и не соответствуют тому, который использовался до того, как я присоединился к компании. Поэтому я попытался прочитать код и получить представление о том, что делает класс (не являясь статистиком), а также попытался выкопать эти отчеты о дефектах. Так получилось, что они были довольно важны и могли бы придумать жизнь следующего парня, чтобы отредактировать файл, не зная о них довольно ужасно, так как он имел дело с незначительными проблемами точности и особыми случаями, основанными на очень специфических требованиях, исходящих от тогдашнего клиента. , Итог, если бы их там не было, я бы не знал. Если бы их там не было И у меня было лучшее понимание класса,
Иногда трудно отслеживать очень старые требования, подобные этим. В конце концов, я все-таки удалил заголовок, но после того, как прокрался в комментарии к блоку перед каждой инкриминирующей функцией, описывающей, почему эти «странные» вычисления являются конкретными запросами.
Так что в этом случае я все еще считал это плохой практикой, но, боже, я был счастлив, что оригинальный разработчик, по крайней мере, вставил их! Лучше было бы вместо этого четко прокомментировать код, но я думаю, это было лучше, чем ничего.