Используете ли вы специальные комментарии к исправлениям ошибок в своем коде?
https://stackoverflow.com/questions/123936
-
02-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianВопрос
Некоторые из моих коллег используют специальные комментарии к своим исправлениям ошибок, например:
// 2008-09-23 John Doe - bug 12345
// <short description>
Есть ли в этом смысл?
Комментируете ли вы исправления ошибок каким-то особым образом?
Пожалуйста, дайте мне знать.
Решение
Я не добавляю подобные комментарии, система управления версиями уже поддерживает эту историю, и я уже могу регистрировать историю файла.
Однако я добавляю комментарии, которые описывают, почему делается что-то неочевидное.Итак, если исправление ошибки делает код менее предсказуемым и понятным, то я объясняю, почему.
Другие советы
Со временем они могут накапливаться и создавать беспорядок.Лучше сделать код понятным, добавить любые комментарии к связанным ошибкам, которые могут быть неочевидными, и сохранить подробную информацию об ошибке в системе отслеживания и репозитории.
Я обычно не комментирую фактический источник, потому что его может быть трудно поддерживать в актуальном состоянии.Однако я помещаю комментарии со ссылками в свой журнал управления версиями и отслеживания проблем.например ,Я мог бы сделать что-то подобное волей-неволей:
[Идентификатор ошибки] Проблема с диалогом xyz.Переместил код определения размера в abc и теперь инициализирую позже.
Затем в моем трекере проблем я сделаю что-то вроде:
Исправлено в списке изменений 1234.
Переместил код определения размера в abc и теперь инициализирую позже.
Потому что тогда остается хороший исторический след.Также это упрощает задачу, если вы хотите узнать, почему конкретная строка кода выполняется определенным образом, вы можете просто просмотреть историю файлов.Как только вы найдете нужную строку кода, вы можете прочитать мой комментарий к фиксации и четко увидеть, к какой ошибке это относилось и как я ее исправил.
Только в том случае, если решение было особенно умным или трудным для понимания.
Обычно я добавляю свое имя, адрес электронной почты и дату вместе с кратким описанием того, что я изменил, потому что как консультант я часто исправляю код других людей.
// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>
Таким образом, владельцы кода или люди, пришедшие после меня, смогут выяснить, что произошло, и они смогут связаться со мной, если потребуется.
(да, к сожалению, чаще всего у них нет контроля версий...для внутренних операций я использую отслеживание TFS)
Хотя в то время это может показаться хорошей идеей, она быстро выходит из-под контроля.Такую информацию можно лучше получить, используя хорошую комбинацию системы контроля версий и отслеживания ошибок.Конечно, если происходит что-то сложное, в любом случае был бы полезен комментарий, описывающий ситуацию, но не дата, имя или номер ошибки.
Кодовой базе, над которой я сейчас работаю на работе, примерно 20 лет, и, похоже, они добавили много комментариев, подобных этому, много лет назад.К счастью, они прекратили это делать через несколько лет после того, как в конце 90-х перевели все на CVS.Однако такие комментарии по-прежнему разбросаны по всему коду, и политика теперь такова: "удалите их, если вы работаете непосредственно над этим кодом, но в остальном оставьте их".Часто им действительно трудно следовать, особенно если один и тот же код добавляется и удаляется несколько раз (да, такое случается).Они также не содержат даты, но содержат номер ошибки, который вам пришлось бы искать в архаичной системе, чтобы найти дату, поэтому никто этого не делает.
Подобные комментарии объясняют, почему Subversion позволяет вам вводить запись в журнале при каждой фиксации.Вот куда вы должны поместить все это, а не в код.
Я делаю это, если исправление ошибки связано с чем-то непростым, но чаще всего, если исправление ошибки требует длинного объяснения, я воспринимаю это как признак того, что исправление было плохо разработано.Иногда мне приходится работать с общедоступным интерфейсом, который не может измениться, поэтому он, как правило, является источником подобных комментариев, например:
// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior. Jump through some hoops to find a default value.
В других случаях сообщение о фиксации системы управления версиями - это то, что я использую для аннотирования изменения.
Хотя я склонен видеть некоторые комментарии к ошибкам внутри кода в процессе работы, мое личное предпочтение - привязывать фиксацию кода к одной ошибке.Когда я говорю "один", я на самом деле имею в виду одну ошибку.После этого вы всегда можете просмотреть внесенные изменения и узнать, к какой ошибке они были применены.
Такой стиль комментирования чрезвычайно ценен в среде с участием нескольких разработчиков, где разработчики обладают различными навыками и / или бизнес-знаниями (например- везде).
Для опытного знающего разработчика причина изменения может быть очевидной, но для начинающих разработчиков этот комментарий заставит их дважды подумать и провести дополнительное расследование, прежде чем возиться с ним.Это также помогает им узнать больше о том, как работает система.
О, и заметка из опыта о комментариях "Я просто поместил это в систему управления версиями":
Если этого нет в источнике, значит, этого не произошло.
Я не могу сосчитать, сколько раз история исходных текстов для проектов терялась из-за неопытности в программном обеспечении управления версиями, неправильных моделей ветвления и т.д.Существует только одно место - история изменений не может быть потерян - и это есть в исходном файле.
Обычно я сначала помещаю это туда, а затем вырезаю и вставляю тот же комментарий, когда регистрирую его.
Нет, я этого не делаю, и я ненавижу, когда подобные граффити засоряют код.Номера ошибок можно отслеживать в сообщении о фиксации в системе контроля версий, а также с помощью скриптов для отправки соответствующих сообщений о фиксации в систему отслеживания ошибок.Я не верю, что им место в исходном коде, где будущие правки только все запутают.
Часто подобный комментарий сбивает с толку, поскольку у вас на самом деле нет контекста относительно того, как выглядел исходный код или исходное плохое поведение.
В общем, если ваше исправление ошибки теперь заставляет код работать КОРРЕКТНО, просто оставьте его без комментариев.Нет необходимости комментировать правильный код.
Иногда исправление ошибки заставляет вещи выглядеть странно, или исправление ошибки тестируется на что-то необычное.Тогда, возможно, было бы уместно добавить комментарий - обычно комментарий должен ссылаться на "номер ошибки" из вашей базы данных ошибок.Например, у вас может быть комментарий, в котором говорится "Ошибка 123 - Объясняется странное поведение, когда пользователь имеет разрешение экрана 640 на 480".
Если вы добавите подобные комментарии после нескольких лет поддержки кода, у вас будет так много комментариев по исправлению ошибок, что вы не сможете прочитать код.
Но если вы меняете что-то, что выглядит правильно (но имеет незначительную ошибку), на что-то более сложное, неплохо добавить короткий комментарий, объясняющий, что вы сделали, чтобы следующий программист, который будет поддерживать этот код, не изменил его обратно, потому что он (или она) думает, что вы чрезмерно усложняете вещи без уважительной причины.
Нет.Я использую subversion и всегда ввожу описание моей мотивации для внесения изменений.Обычно я не пересказываю решение на английском языке, вместо этого я суммирую внесенные изменения.
Я работал над несколькими проектами, где они добавляли комментарии в код при исправлении ошибок.Интересно, и, вероятно, не случайно, что это были проекты, которые либо не использовали какой-либо инструмент контроля версий, либо были обязаны следовать такого рода соглашениям по распоряжению руководства.
Честно говоря, я действительно не вижу смысла делать это в большинстве ситуаций.Если я захочу узнать, что изменилось, я посмотрю журнал subversion и diff.
Только мои два цента.
Если код исправлен, комментарий бесполезен и никому не интересен - просто шум.
Если ошибка не устранена, значит, комментарий неверен.Тогда это имеет смысл.:) Так что просто оставляйте такие комментарии, если вы на самом деле не устранили ошибку.
Чтобы найти конкретный комментарий, мы используем DKBUGBUG - это означает, что исправление Дэвида Келли и рецензент могут легко идентифицировать, конечно, мы добавим дату и другой номер отслеживания ошибок VSTS и т.д. Вместе с этим.
Не дублируйте метаданные, которые ваш венчурный капиталист собирается сохранить для вас.Даты и имена должны быть указаны в списке, автоматически добавляемом VCS.Номера билетов, имена менеджеров / пользователей, которые запросили изменение, и т.д. Должны быть в комментариях VCS, а не в коде.
Вместо этого:
//$ДАТА $ИМЯ $БИЛЕТ // полезный комментарий для следующего бедолаги
Я бы сделал это:
// полезный комментарий для следующего бедолаги
Если код находится на операционной платформе, вдали от прямого доступа к репозиторию системы управления версиями, то я добавлю комментарии, чтобы выделить изменения, внесенные в рамках исправления ошибки в операционной системе.
В противном случае сообщение, которое вы вводите при регистрации, не должно содержать всей необходимой вам информации.
ваше здоровье,
Роб
Когда я вношу исправления / усовершенствования в сторонние библиотеки / компоненты, я часто делаю некоторые комментарии.Это упрощает поиск и перемещение изменений, если мне нужно использовать более новую версию библиотеки / компонента.
В своем собственном коде я редко комментирую исправления ошибок.
Я не работаю над проектами с участием нескольких человек, но иногда добавляю комментарии об определенной ошибке в модульный тест.
Помните, что нет такого понятия, как ошибки, просто недостаточное тестирование.
Поскольку я использую как можно больше TDD (все остальное - социальное самоубийство, потому что любой другой метод заставит вас работать бесконечные часы), я редко исправляю ошибки.
Большую часть времени я добавляю в код специальные замечания, подобные этому:
// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.
Звучит грубо, но большинство людей, называющих себя "разработчиками", не заслуживают никаких других замечаний.
