Комментарии к номеру ошибки
-
03-07-2019 - |
Вопрос
Почему бы вам добавить
//Ошибка 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). Р>
Это хорошо!
Человек, который просматривает код, вряд ли оценит полную историю кода и, вероятно, отменит очень важное изменение, потому что он, возможно, раньше не работал в этой области кода. Он может объяснить код, который в противном случае выглядит безумным, или требование клиента, которое эквивалентно странно.
Вы не можете всегда фиксировать мелкие детали требований клиентов через архитектуру и код, особенно когда они просят что-то глупое. Следовательно, вы начинаете с здравого смысла, а затем уточняете или взламываете код до глупости, когда вы вынуждены это делать, номера ошибок подтверждают намерения сумасшедшего кода.