Номер ошибки

Question

Зачем вы добавляете

// Ошибка 1024

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

Answer 1

Я нашел один из них полезным на днях в нашей базе кода.

Я сказал: «Почему он вызывает функцию инициализации второй раз, так поздно в рабочем процессе ??»

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

Хотя я скажу, что в целом я с вами согласен и сам их не вставляю.

Я бы предпочел, чтобы рассматриваемый разработчик исправил ошибку более осмысленно, чтобы мне не пришлось задумываться о коде.

Answer 2

В конечном счете, я думаю, что это плохая практика. Лучше указать, почему ошибка существует (foos типа Y не имеет свойства Z). Вы можете включить «more in BugId 12345» вместе с этим, если хотите.

Если вы интегрируете на нескольких уровнях, представление исходного кода в trac может напрямую связываться с BugId.

Answer 3

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

Затем вы можете взглянуть на 1024 и посмотреть, что, почему и когда, прежде чем делать новое исправление - «тот, кто будет править ими всеми».

Если номер ошибки не указан в сообщении о коммите, вам необходимо найти ошибку, которую исправил коммит, - и может быть несколько (если об ошибке сообщалось более одного раза).

Answer 4

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

Ошибка 1111 - Foo перестал работать на 64-битных системах. Исправлено # 2, потому что он был вновь открыт после слияния с транком.

Некоторые системы имеют интеграцию с номерами ошибок. В mxr.mozilla.org номер ошибки в отображении журнала cvs автоматически волшебным образом превращается в ссылку на номер bugzilla.mozilla.org. Когда вы копаетесь в коде, это огромная экономия времени. Я думаю, что у Fogbugz есть похожая особенность ...

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

Answer 5

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

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

Я согласен, что номера ошибок должны быть в сообщениях коммитов контроля версий.

Answer 6

Чистая лень. Конечно, в долгосрочной перспективе это займет больше времени, но в краткосрочной перспективе // Bug 1024 не потребует никаких усилий Чем больше у вас кода, тем хуже.

Answer 7

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

Answer 8

Я бы согласился с вами, что такой комментарий не очень полезен и является слишком коротким.

Однако чрезвычайно полезно и важно комментировать код со ссылками на записи в системе отслеживания дефектов (или в том, что касается любого хранилища KM, которое у вас может быть).

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

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

P.S. эта статья о MS Office от Joel On Software может оказаться полезной. Насколько я знаю, код MS Office и MS Windows полон похожих комментариев, которые объясняют решения, принятые разработчиками, давно ушедшими.

Answer 9

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

Что я считаю полезным, так это использование идентификатора дефекта как части имени в автоматических тестах:

[TestFixture]
public class Release_1_2_Bugfixes
{
  [Test]
  public void TestBug42()
  {
    Assert.AreEqual(42, CalculateAnswerToLifeUniverseAndEverything());
  }
}

Я видел другие проекты , делающие то же самое.

Answer 10

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

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

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

РЕДАКТИРОВАТЬ : Я имею в виду специально для обозначения их с блоком кода, который необычен или нуждается в дополнительном контексте. Бесполезно или необязательно комментировать каждое исправление, которое вы делаете: -)