Комментарии к номеру ошибки
https://stackoverflow.com/questions/163232
-
03-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianВопрос
Почему бы вам добавить
//Ошибка 1024
комментарии к базе кода, контролируемой исходным кодом?Большинство систем отслеживания ошибок и контроля версий лучше оснащены для отслеживания этой информации.В системе управления версиями при проверке можно использовать метку или комментарий.В багтрекере номер редакции может быть добавлен к разрешению ошибки.Так зачем же комментировать код?Особенно с учетом того, что релевантность этих комментариев очень недолговечна, и они, как правило, засоряют базу кода.
Решение
Я нашел один из них полезным на днях в нашей базе кода.
Я сказал "почему он вызывает функцию инициализации второй раз, так поздно в рабочем процессе?"
Комментарий к ошибке позволил мне перейти к описанию проблемы. Когда я переустанавливал код, я обязательно включил эту ошибку в свои тесты и больше не вводил ее.
Хотя я скажу, что в целом я согласен с вами и не вставляю их сам.
Я бы предпочел, чтобы рассматриваемый разработчик исправил ошибку более осмысленным образом, чтобы мне не пришлось задумываться о коде.
Другие советы
В конце концов, я считаю, что это плохая практика. Лучше указать, почему ошибка существует (foos типа Y не имеет свойства Z). Вы можете включить " больше в BugId 12345 " вместе с этим, если хотите.
Если вы интегрируете на нескольких уровнях, представление исходного кода в trac может напрямую связываться с BugId.
Чистая лень. Конечно, это займет больше времени в долгосрочной перспективе, но в краткосрочной перспективе " // Ошибка 1024 " не требует никаких усилий. Чем больше у вас кода, тем хуже.
Представьте, что у вас есть новая ошибка, которую вы отслеживаете до изменения в редакции 12345. Вы просматриваете журналы, и сразу же появляется сообщение о том, что ошибка 1024 была причиной внесения изменений.
Затем вы можете посмотреть на 1024, чтобы узнать, что, почему и когда, прежде чем делать новое исправление - «тот, который будет править ими всеми».
Если номер ошибки отсутствует в сообщении о коммите, вам нужно найти ошибку, которую исправил коммит - и может быть несколько (если об ошибке сообщалось более одного раза).
Я думаю, что это случай "у меня есть молоток, который должен быть гвоздем". Ваш текстовый редактор или IDE - не единственный инструмент для управления кодом.
История лучше всего поддерживается внешним образом в коде. Смысл кода должен быть описан в комментариях, если он не очевиден сразу.
Я согласен, что номера ошибок должны быть в сообщениях коммитов контроля версий.
Вы никогда не должны добавлять только номер ошибки. Вы должны добавить номер ошибки и тему, а также любые квалификаторы, если вы сделали несколько проверок для одной ошибки:
Ошибка 1111 - Foo перестал работать на 64-битных системах. Исправьте # 2, потому что он был вновь открыт после слияния с транком.
Некоторые системы имеют интеграцию с номерами ошибок. В mxr.mozilla.org номер ошибки в отображении журнала cvs автоматически волшебным образом превращается в ссылку на номер bugzilla.mozilla.org. Когда вы копаетесь в коде, это огромная экономия времени. Я думаю, что у Fogbugz есть похожая особенность ...
Кроме того, даже если ваша система этого не делает, это часто помогает, потому что никто не хочет видеть весь контекст изменений в комментариях, для этого и предназначен механизм отслеживания ошибок.
Я бы согласился с вами, что подобный комментарий на самом деле не очень полезен и слишком краток.
Однако чрезвычайно полезно и важно комментировать код со ссылками на записи в системе отслеживания дефектов (или на то, что распространяется на любой репозиторий KM, который у вас может быть).
Иногда код изменяется для реализации обходного решения определенной проблемы с поведением приложения.Иногда введенный обходной путь никоим образом не является логичным.Часто случается, что, когда код обновляется кем-то другим, этот "плохой" фрагмент кода удаляется в рамках усилий по повторному факторингу.
Таким образом, пометка кода как относящегося к определенному исправлению ошибки делает его видимым во время повторного факторинга, побуждая разработчика просмотреть описание ошибки перед изменением кода.Это также помогает в ситуации, когда ошибка открывается повторно - если вам приходится изменять одну и ту же часть кода несколько раз, вы можете подумать о том, чтобы потратить время на альтернативное решение.
P.S.вы могли бы подумать это полезная статья о MS Office от Джоэла о программном обеспечении.Насколько я знаю, код MS Office и MS Windows полон подобных комментариев, которые объясняют решения, принятые давно ушедшими разработчиками.
Я считаю это полезным при объяснении кода, который в противном случае может показаться неправильным, а также для использования в сообщениях фиксации.
Я этого не делаю. Я не могу придумать вескую причину, по которой вы добавили бы идентификатор дефекта в код. Вместо этого я добавлю это в заметки о выпуске / журнал изменений.
Я считаю полезным использовать идентификатор дефекта как часть имени в автоматизированных тестах:
[TestFixture]
public class Release_1_2_Bugfixes
{
[Test]
public void TestBug42()
{
Assert.AreEqual(42, CalculateAnswerToLifeUniverseAndEverything());
}
}
Я видел другие проекты делать то же самое.
Я удивлен тем, сколько людей против этого. По моему личному мнению, это хорошая идея. Я согласен с более ранним комментарием о том, что он должен включать не только номер ошибки, но предпочтительно включать краткое резюме и ссылку на систему отслеживания ошибок, если это необходимо.
Преимущество этих комментариев очевидно только в старом проекте с историей и большим количеством предыдущих исправлений ошибок. Вам не нужно делать эти комментарии везде, но они очень полезны, когда помещаются перед блоком кода, который может не иметь смысла без контекста. В любой разумно сложной системе будут фрагменты кода, которые кажутся нелогичными или ненужными без контекста.
Из-за взаимодействия с системой или из-за старых обходных путей, код необходим . Чтобы предотвратить повторное внесение исправленной ошибки, крайне полезно обозначить ошибку, которую должен исправить блок кода, желательно с некоторыми пояснениями. В противном случае вы зависите от того, кто-то тщательно проверяет историю коммитов по причине, записанной в журнале коммитов, что весьма маловероятно, особенно если кто-то реорганизует код.
РЕДАКТИРОВАТЬ . Я имею в виду именно то, что в них есть блок кода, который необычен или требует дополнительного контекста. Бесполезно или необязательно комментировать каждое исправление, которое вы делаете: -)
Я делал это вплоть до выпуска Visual Studio 2008 с аннотацией. При просмотре старого кода было полезно сразу увидеть, что, по крайней мере, задумывалось конкретное решение кода.
Да, я знаю, что вы можете сравнить с предыдущими версиями, но это такая боль в заднице, когда вам просто нужно быстро позаботиться о небольших обновлениях кода.
Если вы просматриваете незнакомый исходный код и видите что-то неочевидное, приятно знать причину. Хотя это и есть суждение, не каждое исправление ошибки нуждается в таком объяснении - вероятно, большинство может обойтись без него.
Если есть достаточно оснований полагать, что кто-то захочет узнать номер ошибки при просмотре части кода, добавление комментария с упоминанием об ошибке может быть весьма полезным (надеюсь, это перефразирует и важные части ошибки, однако).
Да, сообщения коммитов контроля версий также должны содержать номера ошибок, и просмотр журналов ревизий может дать вам ту же информацию ... но если одна и та же часть кода изменяется несколько раз, но детали извлекаются из Первоначальная ошибка по-прежнему применяется, может потребоваться некоторое время, чтобы найти оригинальное изменение, чтобы когда-либо узнать об этой ошибке.
Кроме того, возникают ситуации, когда есть веская причина для перемещения кода из одного класса в другой или для переименования файлов, что затруднит поиск корня причины для определенной части кода (переименование не так большая часть проблемы с SVN, но боль с CVS).
Вы ударили по голове "релевантность очень коротка, и они имеют тенденцию накапливать мусор на базе кода. "
Каждый бесполезный мусор, который накапливается в исходных файлах, делает их немного менее читабельными и сложными в обслуживании. Удалите все, что не добавляет ценности. "Ошибка 12345" имеет мало значения сейчас, и через несколько недель его не будет.
Мы работаем в крупномасштабной системе со многими разработчиками и несколькими выпущенными ветками.
Эти комментарии об ошибках могут быть весьма полезны при переносе из одной ветки в другую, тем более что используемая нами система SCM очень плоха, а коммитить комментарии сложно, или они могут быть довольно старыми.
Если исправление было простым, ему может не понадобиться маркер ошибки. Если это неочевидно, может иметь смысл обратиться к ошибке, чем написать длинное объяснение в разделе комментариев.
Мне не нравятся такие граффити. Как и другие неприятные формы жизни, они накапливаются со временем, задыхаясь от кода.
Проблема действительно начинается, когда люди исправляют ошибки, которые перекрывают предыдущее исправление. Затем у вас есть номера ошибок, обозначающие часть кода, которая просто неверна или вводит в заблуждение.
Этот тип комментариев IS очень полезен: что происходит, когда вы меняете инструменты отслеживания ошибок или контроля версий? Ссылка на BZ1722 против FB3101 скажет вам, какой инструмент отслеживания следует проверить (например, Bugzilla или FogBugz).
Это хорошо!
Человек, который просматривает код, вряд ли оценит полную историю кода и, вероятно, отменит очень важное изменение, потому что он, возможно, раньше не работал в этой области кода. Он может объяснить код, который в противном случае выглядит безумным, или требование клиента, которое эквивалентно странно.
Вы не можете всегда фиксировать мелкие детали требований клиентов через архитектуру и код, особенно когда они просят что-то глупое. Следовательно, вы начинаете с здравого смысла, а затем уточняете или взламываете код до глупости, когда вы вынуждены это делать, номера ошибок подтверждают намерения сумасшедшего кода.
