Почему цитирование идентификаторов ошибок в примечаниях к исправлению может считаться плохой практикой?

28

Основываясь на комментарии и последующие отзывы от Bug вновь открываются против новых :

Цитировать идентификаторы ошибок в примечаниях к патчу просто ... очень недружелюбно. - Крелп

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

issue-tracking bug-report software-patches

— Трэвис Норткатт
источник

27

не ссылаться на идентификаторы ошибок в примечаниях к патчу просто ... очень непрофессионально. Вид мусора весь смысл наличия трекера проблемы

— комара

По той же причине, по которой публикация только ссылок в ответах StackExchange не одобряется - если вы публикуете только ссылку, на SE это плохо, потому что (1) требуется следовать, чтобы получить объяснение, и (2) может стать недействительным в будущем, если ссылка умирает или содержание меняется. Точно так же для размещения только идентификаторов ошибок в примечаниях к исправлению (1) требуется обратиться к средству отслеживания ошибок, чтобы получить объяснение, и (2) может стать недействительным в будущем, если система отслеживания ошибок изменится. Включение ссылки в SE-ответ или идентификатор ошибки в примечании к патчу - это хорошо (и на самом деле хорошая практика) как дополнение к регулярному объяснению.

— Бен Ли

51

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

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

— Карл Билефельдт
источник

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

— Донал Феллоуз

Как вы говорите, раздел «Исправленные ошибки» (или аналогичный) должен содержать идентификатор и заголовок, чтобы читателю не пришлось искать ошибку, чтобы точно понять, что включено, а что нет.

— StuperUser

5

@StuperUser - Идентификатор и заголовок, как минимум .

— Одед

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

— jfrankcarr

14

Это, как сказано в цитируемом комментарии ... недружелюбно.

Недружественный к себе

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

Решено # 1307

Вы запускаете систему отслеживания ошибок, надеясь получить что-то полезное. Ошибка № 1307 сообщается как исправленная. В описании вы видите:

Та же ошибка, что и # 1284

Спасибо, это очень полезно. Теперь вам нужно перейти к сообщению об ошибке № 1284, чтобы прочитать, что это дубликат ошибки № 1113, которая относится к ошибкам № 1112, № 1065 и № 1067.

Пять минут спустя, вы не знаете, что вы ищете в начале.

Гораздо более полезным регистрационное сообщение управления версиями будет:

Устранена проблема, из-за которой пользователи не могли войти в систему с паролем длиной более 25 символов (см. № 1307), удалив применение к слою доступа к данным той же политики длины пароля, что и на самом веб-сайте.

Точно так же в системе отслеживания ошибок отчет № 1307 может быть более понятным , напоминая, о чем был отчет об ошибке № 1284, и чем новый отличается от старого.

Недружественный с клиентами

Это не единственная проблема дружелюбия.

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

Здесь более подробные сообщения очень полезны, чем просто ссылка. Обратите внимание, что вы все еще хотите сохранять ссылки: нет ничего более неправильного, чем ошибка, которая совпадает с ошибкой, с которой вы столкнулись две недели назад, но не вызывайте ее ID.

Как примечание, та же проблема существует во многих юрисдикциях. Например, во Франции законодательство часто ссылается на несколько источников, которые могут измениться между тем. Это означает, что для того, чтобы полностью понять это, вы должны иногда проводить часы в библиотеке, ища десятки упомянутых текстов, каждый из которых имеет свои ссылки на другие.

— Арсений Мурзенко
источник

5

Это не проблема с документом релиза; это проблема с уровнем детализации ошибок. Название должно описывать реальную проблему, а тело каждой ошибки имеет ожидаемый результат и фактический результат. Не должны ли ошибки, как вы описали, быть дубликатами?

— StuperUser

На основании вашего редактирования. Вы указали идентификатор в своем гораздо более полезном сообщении. Вы имели в виду в своем первоначальном комментарии, что цитирование ТОЛЬКО идентификаторов без дополнительной информации бесполезно, тогда как правильное объяснение И идентификатор полезны?

— StuperUser

1

@StuperUser: точно. Предоставление объяснения помогает людям, которые просто хотят знать, что такое журнал фиксации / исправление / отчет об ошибке, не тратя десять минут на чтение ссылочного содержимого. Идентификаторы все еще необходимы для отслеживания и людей, которые нуждаются в очень подробной, точной и полной информации.

— Арсений Мурзенко

2

Нет ничего плохого в том, чтобы ссылаться на номера проблем в примечаниях к исправлению, при условии, что пользователи могут прочитать проблему, которая цитируется. Если ваша база данных ошибок позволяет кому-либо читать, цитирование номера ошибки действительно может быть очень полезным. (Еще лучше, если ваши примечания к исправлениям имеют формат, разрешающий ссылки, сделайте эти идентификаторы проблем ссылками на рассматриваемый вопрос.) Это не означает, что вы должны раскрывать все проблемы для широкой публики; все еще может быть полезно иметь скрытые (например, там, где у них есть действующие пароли!)

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

— Donal Fellows
источник

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

— комари

2

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

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

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

Посмотрите, например , на журнале изменений в Visual Assist X . Все эти связанные идентификаторы ошибок - просто шум, который отвлекает меня от понимания того, что изменилось. И это дополнение для Visual Studio, предназначенное для программистов. И я программист. Если это беспокоит меня, представьте себе обычного пользователя, который даже не знает, что такое баг-трекер.

PS: я был автором комментария, который вызвал вопрос

— Томас Бонини
источник

1

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

— Джошуа Дрейк

1

Идентификатор ошибки является обязательным для ссылки . Причины:

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

3052 был уже исправлен, все еще работает на 3077

удобнее чем:

Исправлено «падение приложения при нажатии кнопки», по-прежнему работало над «NullReferenceException при нажатии на изменение пользователя»

— KMoraz
источник

(1) Что мешает вам комбинировать его, как предлагает MainMa? (2) Почему вы исправляете полтора исправленных ошибки? Почему бы вам не выполнить фиксацию после исправления 3052, прежде чем вы даже начнете работать на 3077?

— JensG

0

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

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

— wildpeaks
источник