Чому цитування ідентифікаторів помилок у виправлених нотах можна вважати поганою практикою?

На підставі коментаря та подальших оновлень помилки відновлюються порівняно з новими :

Посилання ідентифікаторів помилок у виправлених нотах просто .. дуже недружелюбно. - Крелп

Здається, принаймні, деякі люди вважають, що посилання на ідентифікатори помилок у патч-нотах не є хорошою ідеєю. Я досить недосвідчений розробник, тому мені цікаво, чому це так.

На мою думку, це хороша практика, якщо припустити, що ваші користувачі прочитали доступ до вашої бази помилок. Буває багато випадків, коли люди чекають виправлення певної помилки, щоб вирішити, коли оновити.

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

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

Недружні з собою

Уявіть такий сценарій. Ви переглядаєте журнали в керуванні джерелами. Вам цікаво, що змінився комітет. Замість того, щоб пояснювати це простою англійською мовою, воно говорить вам:

Вирішено # 1307

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

Та сама помилка, як # 1284

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

Через п’ять хвилин ви не знаєте, що шукаєте на початку.

Набагато кориснішим реєстраційне повідомлення управління версіями буде:

Вирішено проблему з тим, що користувачі не можуть увійти в систему з паролем, довшим ніж 25 символів (див. № 1307), видаливши застосувати ту саму політику щодо довжини пароля до рівня доступу до даних, що використовується на самому веб-сайті.

Таким же чином у системі відстеження помилок звіт № 1307 міг би бути більш зрозумілим , нагадуючи, про що був звіт про помилку №1284, і чим новий відрізняється від старого.

Недружні з клієнтами

Це не єдине питання дружелюбності.

По-друге, це те, що, посилаючись на занадто багато інформації, не маючи додаткової інформації, ви робите патч-замітки / журнали контролю версій / звіти про систему відслідковування помилок, непридатними для тих, хто не дуже знайомий з цими системами . Щодня ви працюєте із системою відстеження помилок, ви знаєте, як швидко орієнтуватися у звітах, переглядати декілька звітів поруч тощо. Коли ви є клієнтом, який не має технічного досвіду, вас легко втратити.

Тут ще раз, більш детальні повідомлення є корисними, ніж просто посилання. Зауважте, що ви все ще хочете зберегти посилання: нічого більш поганого, ніж помилка, яка не збігається з помилкою, з якою ви стикалися два тижні тому, але не пам’ятайте її ідентифікатор.

Як зауважимо, те саме питання існує у багатьох юрисдикціях. Наприклад, у Франції незвично законодавство посилається на декілька джерел, які можуть змінюватися тим часом. Це означає, що для того, щоб повністю зрозуміти це, вам доводиться іноді проводити години в бібліотеці, шукаючи десятки згаданих текстів, кожен текст має свої посилання на інші.

Немає нічого поганого в тому, що цитувати номери випусків у виправлених нотах, за умови, що користувачі можуть прочитати проблему, яку цитують. Якщо ваша база помилок дозволяє комусь читати, цитування номера помилки може бути дуже корисним. (Ще краще, якщо ваші ноти виправлень у форматі, що дозволяє посилання, перетворіть ці ідентифікатори випусків на посилання на цю проблему.) Це не означає, що ви повинні виставляти всі питання широкій громадськості; все ще може бути корисно мати зашиті (наприклад, де у них є живі паролі!)

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

Очевидно, хто є тим, хто буде читати патчі, а також цільовими користувачами програмного забезпечення.

Але в більшості випадків переважній більшості користувачів просто не цікаво, що таке ідентифікатор помилки. Їм не байдуже, чому це було зламано, що таке виправлення чи що-небудь інше - вони хочуть знати лише те, що змінилося з дуже лаконічним текстовим описом без необхідності переходити на іншу сторінку для кожної зміни.

Посилання на ідентифікатори помилок змушує мене зупинятися і думати, і я - як користувач - не хочу думати. Це свого роду питання зручності використання.

Подивіться, наприклад , на журналі змін в Visual Assist X . Усі ці пов'язані ідентифікатори помилок - це лише шум, який відволікає мене від розуміння того, що змінилося. І це доповнення для Visual Studio, орієнтованого на програмістів. А я програміст. Якщо це мене турбує, уявіть середнього користувача, який навіть не знає, що таке трекер помилок.

PS: Я був автором коментаря, який викликав питання

Ідентифікатор помилки є обов'язковим для точки відліку . Причини:

• Запобігати двозначності: Два чи більше помилок можуть мати подібні описи. Тому для розрізнення між ними потрібен буде якийсь якор.
• Зручність : Під час обговорення помилки з клієнтом або зсередини, ідентифікатор помилки часто використовується як коротка форма. Якщо ідентифікатор буде опущений із заміток патча, про них буде важко обговорити:

3052 було вже зафіксовано, і досі працює на 3077

зручніше ніж:

Виправлено "збій програми при застосуванні", він все ще працює над "NullReferenceException при натисканні зміни користувача"

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

Але якби я був у системі, де вона недоступна, я б все-таки зазначив ідентифікатор квитка (таким чином ви можете швидко шукати в журналах за ідентифікатором квитка ) разом з коротким описом того, що таке помилка.